Artifex

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

Artifex помогает проверять организационные изменения по документам: находит возможные потери функций, пересечения ответственности и противоречия с указанием источников. Проект команды Artifex для HackAlem AI, трек «Анализ организационной структуры и функционала».

2. Краткое описание

Сотрудник загружает документы «до» и «после» реорганизации и получает изменения структуры, кандидаты на потерю или передачу функций, возможные отклонения и аналитическое заключение с цитатами и рекомендациями.

Пример из контрольной выдержки. В редакции 8 пункт 5.6.3 закрепляет за ДККМ право вносить предложения по объёму и содержанию внешней оценки. В редакции 9 система не находит соответствующего полномочия, хотя пункт 11.2 сохраняет требование проводить внешнюю оценку не реже одного раза в пять лет. Python-движок выдаёт L-5.6.3 и O-11.2: возможный разрыв между обязательством и полномочием. Сотруднику нужно проверить распределение ответственности и другие документы; система не доказывает, что оценка фактически не проводится.

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

В репозитории два приложения: Python-приложение с русскоязычным заключением и Lineage на TypeScript с извлечением графа, функций и проверкой результатов. Это отдельные аналитические движки; загрузчик Word из Python переиспользуется в Lineage.

Требование	Реализация	Как проверить
Изменения подразделений	Python сопоставляет аббревиатуру, название, функции и состав должностей. Lineage использует идентификаторы, названия и явно заданные соответствия.	Открыть «Контрольный комплект» и вкладку «Структура»: появляются ДИТААД и ДОА.
Сопоставление функций и возможные потери	Python ищет сохранение, передачу и ненайденные полномочия. Lineage сравнивает нормализованные поля, область действия и числовые ограничения; поддерживает частичное покрытие, разделение и объединение функций.	Проверить L-5.6.3; в Lineage открыть Function lineage на синтетическом примере.
Дублирование и потенциальные конфликты	Отдельные правила проверяют пересечение функций, противоречия с запретами и признаки самооценки. Lineage также проверяет совмещение исполнения, утверждения и независимого аудита.	В контрольном комплекте проверить дублирование пунктов 5.1.4 и 5.3.7 и основания вывода по 11.1.
Источники существенных выводов	Выводы содержат цитаты и номера пунктов; код проверяет присутствие цитат в тексте. JSON v2 дополнительно проверяет смещения, идентификаторы пунктов и хеши документов.	Раскрыть вывод и открыть цитату в источнике.
Итоговое аналитическое заключение	Python формирует сводку, объяснения и рекомендации; доступны JSON-экспорт и копирование текста. Lineage экспортирует HTML, CSV и JSON с результатами проверки.	Просмотреть заключение после анализа или запустить python3 run.py.

Наличие детектора не гарантирует обнаружение всех случаев. Метки риска и рекомендации требуют проверки сотрудником.

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

Загрузка → извлечение текста и пунктов → сопоставление подразделений и функций → проверка отклонений → открытие источников → заключение. В Python-интерфейсе загружаются комплекты .docx или текстовых файлов. Сотрудник раскрывает вывод, изучает цепочку его получения, открывает цитаты в исходных документах и проверяет рекомендацию.

В Lineage сценарий начинается в Document extraction: загрузить документы или выбрать Edition 8 / 9, при необходимости добавить нормативные тексты и документы других операторов, выполнить извлечение, проверить Graph, Functions, Issues, Context и JSON, затем нажать Compare JSON. Дополнительные проверки дают только цитируемые кандидаты, а не правовое заключение или оценку лучшей практики. Функции без установленного владельца остаются в JSON, но исключаются из сравнения ответственности с явным предупреждением. В результатах анализа можно подтвердить или отклонить находку и оставить комментарий. Печатное заключение показывает структурные изменения, вывод, план действий и краткую выборку из очереди проверки; полный список остаётся в JSON и CSV.

5. Технологии

• Python-приложение: Python 3, стандартная библиотека, ThreadingHTTPServer, HTML/CSS/JavaScript. Анализ использует регулярные выражения, лексическое сходство, эвристическое сопоставление подразделений и отдельные правила отклонений.
• Lineage: TypeScript, Node.js 24+, React, Vite, Express, Zod, SQLite, React Flow, Dagre и Graphlib. Сравнение использует индекс кандидатов, канонические поля функций, проверку пересечения областей и покрытия интервалов. Тестирование: Vitest.
• Извлечение документов: текст, Markdown и Word; для текстовых PDF используется pypdf, для Excel — openpyxl. Сканированные документы требуют внешнего OCR.
• LLM в Lineage: OpenAI Responses API, структурированные ответы по Zod-схемам и собственный ограниченный цикл вызова инструментов. Специалисты по структуре, функциям и проверке могут искать и читать пункты загруженных документов. Код назначает идентификаторы, проверяет источники и граф, кэширует ответы и ограничивает число вызовов. Зависимости от Agents SDK нет.
• LLM в Python: адаптеры OpenAI Chat Completions и Anthropic Messages. Модель может уточнять смысловое совпадение выбранной пары, если лексическое сходство попало в диапазон 0.18–0.45. Итоговое заключение формируют правила.

Без LLM работают Python-анализ, сравнение готовых нормализованных графов и локальное извлечение Lineage. Локальное извлечение формирует структурный базис и нераспределённые кандидаты функций. Протокол взаимодействия с моделями проверен подставными ответами; качество живой модели на полных контрольных документах пока не измерено.

6. Запуск

Все команды выполняются из корня проекта. Для основного сценария нужен Python 3; проверка выполнена на Python 3.14.4. Внешние пакеты не требуются:

python3 webapp/server.py

Открыть Python-приложение и нажать «Контрольный комплект». Для собственных данных выбрать файлы «до» и «после». При занятом порте: python3 webapp/server.py --port 8001.

Для Lineage нужны Node.js 24+, npm и Python:

npm ci
npm run dev

Открыть Lineage; при занятом порте сервер напечатает следующий свободный адрес. Для агентного режима указать в .env серверный OPENAI_API_KEY, при необходимости OPENAI_MODEL (по умолчанию gpt-4.1-mini), и перезапустить сервер. Настройки Python-адаптера отдельные: ARTIFEX_AI, ARTIFEX_AI_KEY, ARTIFEX_AI_MODEL. Для PDF и Excel установить requirements-input.txt в виртуальное окружение и задать PYTHON_BIN на его интерпретатор.

7. Архитектура и API

Python: core.py разбирает нормы, units.py сопоставляет структуру, detect.py применяет правила, verify.py проверяет цитаты, summary.py формирует заключение. Сценарий «обязательство сохраняется, полномочие не найдено» реализован здесь отдельным правилом orphan_obligations; в движок Lineage он напрямую не перенесён.

Lineage: server/extraction/ извлекает данные, graph.ts передаёт их в сравнительный движок, server/engine/ формирует результаты, SQLite хранит завершённые извлечения, анализы и решения проверяющего. JSON v2 содержит before и after; в каждой редакции — graph.nodes, graph.edges, functions, источники, проблемы и метрики. Подразделения, должности, внешние органы и группы различаются; функциональное и административное подчинение представлены отдельными типами связей.

Основные HTTP-интерфейсы Lineage: POST /api/documents, POST /api/extraction-jobs, GET /api/extraction-jobs/:id, POST /api/analyze. Контракт находится в shared/extraction.ts, JSON Schema — в examples/extraction-pair.schema.json. Подробности: docs/agentic-extraction.md.

8. Контрольные данные

corpus/rev8.txt и corpus/rev9.txt содержат подготовленные выдержки из реальных редакций положения о внутреннем аудите; golden/golden.json — командную разметку ожидаемых находок. Полные Markdown-экспорты документов находятся отдельно в corpus/full/. Разметка выдержек не является полным эталоном для этих документов.

Для полных редакций проверяются конкретные структурные случаи: два департамента против четырёх по пункту 3.4, разные линии подчинения по 1.5–1.6, одноимённые должности в разных подразделениях, контекст запретов и перенумерация. Встроенный граф Lineage — отдельный синтетический пример.

9. Проверка и результаты

python3 run.py
python3 tests/smoke.py
python3 tests/ai_seam.py
npm test
python3 tests/document_bridge_test.py
npm run build

run.py создаёт out/report.html и out/findings.json. В проверенном прогоне без LLM разобраны 44 и 42 пункта, получены 23 вывода, зачтены 14 из 25 размеченных случаев: полнота 56%. Совпадение засчитывается по типу вывода и основному пункту. Ещё 9 выводов не сопоставлены с разметкой и требуют ручной оценки; precision не установлен. Контроль цитат отклонил 0 выводов, заданные негативные тесты пройдены.

Дополнительно прошли 74 теста TypeScript, 8 тестов загрузки документов, Python-проверки регрессий и адаптера модели. Эти результаты подтверждают проверенные сценарии, а не универсальную точность системы.

10. Ограничения и данные

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

Это локальный однопользовательский прототип без промышленной системы доступа. При включении LLM текст передаётся выбранному API-провайдеру; ключи остаются на сервере. Lineage хранит документы и результаты в .data/, которую следует считать конфиденциальной. Процент обработанных пунктов не является оценкой точности или подтверждением человеком.

11. Ценность и развитие

Artifex показывает путь от изменения документа к возможному организационному последствию и конкретному источнику. Сотрудник получает список вопросов для проверки. Экономия рабочего времени пока не измерена.

Следующие шаги команды Artifex: объединить два аналитических приложения; проверить агентное извлечение на полных размеченных документах с живой моделью; измерить precision, recall, время и стоимость; расширить обработку полномочий и обязательств между документами; добавить OCR и корпоративное управление доступом.