OrgLens AI

Explainable Organizational Change Agent · HackAlem AI 2026 · спецтрек «Казахтелеком».

Текущие проверки интеграции и исправления сопоставления: checkpoint 5. Предыдущие проверки: checkpoint 4, checkpoint 3 и checkpoint 2.

Совместный запуск без API-ключа и документов организатора

Node.js 22.13+ и Python 3.12+. Команды Windows PowerShell выполняются из корня репозитория. Для первой установки зависимостей нужен интернет; после установки deterministic-анализ работает локально. .env, OpenAI-ключ и документы организатора для этого пути не нужны. Освободите порты 8000 и 5173. Backend и frontend запускаются в двух терминалах:

# Терминал 1
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-lock.txt
$env:ANALYSIS_MODE = 'deterministic'
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --host 127.0.0.1 --port 8000

# Терминал 2
npm ci
$env:VITE_USE_MOCK = 'false'
$env:VITE_API_BASE_URL = ''
npm run dev

Откройте http://127.0.0.1:5173. По умолчанию пользовательские DOCX идут в настоящий backend через Vite proxy; OpenAI-ключ для детерминированного режима не нужен. Метка LIVE ANALYSIS означает запрос к backend, а DEMO DATA — локальный синтетический набор. Режим анализа deterministic / semantic показывается по ответу сервера; LIVE ANALYSIS сам по себе не означает использование LLM. «Загрузить демодокументы» доступно в обоих режимах. Для проверки сборки остановите dev-сервер и запустите npm run build, затем npm run preview -- --port 5173 при работающем backend.

Backend /api/health доступен на порту 8000 напрямую и через frontend /api/health. Секреты остаются только в окружении backend. .env.example содержит настройки обеих частей; backend загружает .env только с явным --env-file .env, Vite читает .env и .env.local (в браузер экспортируются только VITE_*).

Проверка на синтетических DOCX с известными изменениями

Оставьте оба сервера запущенными. В третьем терминале из корня репозитория:

(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8000/api/health).Content
(Invoke-WebRequest -UseBasicParsing http://127.0.0.1:5173/api/health).Content
.\.venv\Scripts\python.exe -m scripts.smoke_known_answer

Оба health-запроса должны вернуть {"ok":true}, а smoke — завершиться с кодом 0 и строками PASS. Скрипт не запускает backend: по умолчанию обращается к уже работающему http://127.0.0.1:8000, создаёт синтетические DOCX и отправляет их настоящим HTTP-запросом с mode=deterministic. Ключ и документы организатора не используются; OpenAI не вызывается.

В ignored-каталоге artifacts/known-answer/ появятся known-before.docx, known-after.docx, expected.json и deterministic-response.json. Для проверки UI выберите эти два DOCX на странице 5173 и нажмите «Анализировать изменения». Должны отображаться LIVE ANALYSIS и «Детерминированный анализ», затем граф, функции, выводы, источники и Markdown-экспорт. Это настоящий backend на синтетических входных документах, не semantic-запуск Astra и не встроенный DEMO DATA.

Smoke проверяет заранее заданные изменения и точность ссылок на источники конкретного синтетического примера. Это проверка воспроизводимости, не измерение точности продукта. Переименование и заключение модели проверяются только отдельным платным --mode semantic; для обычного запуска этот параметр не нужен. Адрес и каталог можно изменить через --base-url и --output-dir.

GET /api/demo требует локальные контрольные DOCX и без них возвращает 404. Кнопка frontend «Загрузить демодокументы» использует собственный синтетический набор и работает без этих файлов и без backend.

Problem

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

Solution

Русскоязычная панель сравнения «до → после»: граф преобразований, таблица функций и карточки выводов. Для каждого существенного вывода можно открыть документ, пункт, фрагмент, объяснение и рекомендацию. Итоговое заключение собирает результаты в одном месте.

What is implemented

• Выбор пары DOCX до 10 МБ каждый для API и однокнопочный синтетический демосценарий.
• Раздельные LIVE ANALYSIS / DEMO DATA, ожидание ответа API и повторный запуск через «Сбросить демо».
• Сводные показатели, граф подразделений, сопоставление функций и список выводов.
• Панель оснований с явным статусом «Требует проверки» (NEEDS_REVIEW).
• Аналитическое заключение со скачиванием в Markdown; состояния загрузки, недоступности API, некорректного ответа и пустого списка выводов.
• Сохранённый синтетический demo и подключённый через адаптер настоящий FastAPI backend.
• Предупреждения сервера и «Действия сервиса» после ответа; аналитическая записка с её статусом и основаниями в заключении и Markdown, если она пришла от CORE.

Architecture

React + TypeScript + Vite. UI получает общий объект анализа через сервисный адаптер; деморежим возвращает локальный JSON. API-адаптер отправляет POST /api/analyze с multipart/form-data: before_file и after_file.

Контракт результата: analysis_id, before_document, after_document, units, transformations, function_matches, findings, summary. Перед показом валидатор проверяет поля, ссылки на ID, основания и согласованность счётчиков. Правила адаптации ответа CORE к UI: API_CONTRACT.md; исходные типы — src/types.ts.

Frontend и автоматические проверки

Для запуска только frontend из корня проекта (API-анализ требует backend из инструкции выше; локальный DEMO DATA работает без него):

npm ci
npm run dev

Откройте локальный адрес из вывода Vite. Для полного набора проверок нужны установленный Google Chrome и Python-зависимости из requirements-lock.txt. Перед E2E остановите запущенный вручную backend на 8000 клавишами Ctrl+C: тесты поднимают собственный сервер. Освободите также порты 5175–5177. В отдельном PowerShell:

$env:VITE_USE_MOCK = 'false'
$env:VITE_API_BASE_URL = ''
$env:LIVE_SEMANTIC_SMOKE = '0'
npm test
npm run build
npm run test:e2e

npm test проверяет адаптер и оба формата данных. E2E использует установленный Google Chrome: порты 5175 (локальное synthetic demo), 5176 (ответы и ошибки API с перехватом запросов) и 5177 (production build + настоящий CORE без перехвата). Live-тест использует локальные DOCX из data/, а при их отсутствии создаёт синтетические DOCX внутри репозитория и отправляет их в настоящий backend. Это проверка интеграции, не качества на документах организаторов. Тесты запускают собственный backend из .venv на 8000 в режиме deterministic; перед запуском освободите этот порт.

Перед E2E выполните npm run build с VITE_USE_MOCK=false либо без этой переменной и с пустым VITE_API_BASE_URL. Тестовые frontend-порты должны быть свободны. Playwright хранит временные профили внутри artifacts/tmp, результаты — в test-results и playwright-report.

По умолчанию включён реальный API. Для автономного mock-режима можно создать .env.local:

VITE_USE_MOCK=true

Реальный API используется при VITE_USE_MOCK=false или отсутствии этой переменной. Vite dev/preview перенаправляет /api на http://127.0.0.1:8000; при отдельном адресе сервера задайте VITE_API_BASE_URL, например http://localhost:8000. Сервер должен разрешать запросы с адреса frontend через CORS либо быть доступен за общим origin. После изменения переменных перезапустите Vite; для готовой сборки выполните npm run build заново. Секреты в VITE_* не хранятся: эти значения попадают в клиентскую сборку.

Demo

«Загрузить демодокументы» → «Анализировать изменения» → этапы обработки → «Обзор изменений», «Сравнение функций», «Риски и выводы» → открыть основание → раздел «Заключение» → «Сформировать заключение» → «Скачать заключение». Для повторения нажмите «Сбросить демо». Подготовленное demo доступно и в API-режиме; его выбор не отправляет запрос на сервер.

Для live-показа выберите два DOCX вместо демодокументов. До ответа показано ожидание без вымышленных процентов и стадий; после ответа «Действия сервиса» показывает распознанные завершённые действия из agent_trace. Это журнал действий, не поток прогресса и не chain-of-thought. При сбое можно явно перейти к DEMO DATA, не меняя сборку.

Сценарий на 2–3 минуты · Резервный показ · Ответы жюри · Текст для сдачи.

Data

Все данные, названия документов и цитаты в демосценарии синтетические. Это не документы Казахтелекома. Сюжет: 3 подразделения становятся 4; «Цифровое развитие» разделено на «ИТ» и «Цифровые продукты», «Внутренний контроль» переименован в «Риски и комплаенс», «Эксплуатация сети» сохранена. Набор содержит 5 передач функций, 1 возможную потерю, 2 дублирования и 1 потенциальный конфликт.

В mock-режиме выбранные пользователем файлы не разбираются и не отправляются на сервер; кнопка анализа для них отключена. Результат доступен после выбора «Загрузить демодокументы». Индикатор этапов имитирует работу агента только в этом сценарии. При анализе своих файлов в API-режиме показано ожидание ответа без вымышленных этапов.

Limitations

• Реальные DOCX обрабатываются backend CORE. PDF/TXT/OCR не поддерживаются; UI согласован с ограничением 10 MiB.
• Confidence в mock задан вручную и не является откалиброванной вероятностью.
• VERIFIED в демо означает наличие подготовленных оснований в синтетическом наборе, а не независимую проверку реальных документов.
• В live-анализе интерпретационные выводы и аналитическая записка CORE остаются NEEDS_REVIEW. Неполные основания отображаются с предупреждением; неподтверждённый вывод не превращается в подтверждённый.
• Отсутствие функции в новой редакции и потенциальный конфликт требуют экспертной проверки: NEEDS_REVIEW. Нельзя считать отсутствие найденной цитаты доказательством отсутствия функции.
• Backend в режиме semantic формирует заключение модели с источниками (summary.analytical_note). Frontend показывает и экспортирует его вместе со статусом и основаниями; непосредственно LLM он не вызывает. Это не юридическое заключение.
• Аутентификация, серверное хранение и производственная обработка конфиденциальных документов не реализованы.

---

Backend CORE — запуск, анализ и evidence lock

Backend MVP для HackAlem AI 2026, спецтрек Казахтелеком. Сравнивает два DOCX и возвращает структурированный JSON с подразделениями, функциями, отношениями и точными источниками.

Быстрый запуск backend (Windows PowerShell, Python 3.12+)

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-lock.txt
$env:ANALYSIS_MODE = 'deterministic'
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --host 127.0.0.1 --port 8000

Swagger: http://127.0.0.1:8000/docs. Машиночитаемый контракт: http://127.0.0.1:8000/openapi.json.

requirements-lock.txt фиксирует проверенное окружение, включая тестовые зависимости. Диапазоны прямых зависимостей находятся в requirements.txt и requirements-dev.txt.

DOCX → JSON через CLI

После успешного scripts.smoke_known_answer можно повторно обработать созданную им пару через CLI. Для самого CLI работающий HTTP-сервер не нужен:

.\.venv\Scripts\python.exe -m backend.cli artifacts\known-answer\known-before.docx artifacts\known-answer\known-after.docx --mode deterministic --output artifacts\known-answer\cli-comparison.json

CLI принимает любые два DOCX, а не только контрольные редакции. artifacts/, входные DOCX и .env исключены из Git. Сохраняемый JSON содержит исходные фрагменты; он остаётся локальным. В репозитории нет копий документов или готового ответа на контрольный dataset.

Документы организатора в data/ — необязательные локальные входные данные для отдельных проверок: одна редакция *_8_*.docx и одна *_9_*.docx. Не копируйте их в Git. Их отсутствие не мешает запуску приложения и проверке smoke_known_answer.

Режимы анализа

По умолчанию deterministic: работает без ключа и сети, извлекает явные перечни подразделений и функции из контекста обязанностей, ищет точные и близкие текстовые соответствия. FUNCTION, RIGHT, PROHIBITION различаются; запреты наследуются вложенными пунктами. При неоднозначном назначении функции ownership_status=NEEDS_REVIEW.

semantic использует официальный OpenAI SDK, Responses API и строгий JSON schema. Модель предлагает переименования, разделения, объединения, переносы, изменения функций, риски и аналитическое заключение. Python принимает только существующие ID объектов и источников с правильной стороны сравнения; цитаты и номера пунктов модель не генерирует. Инструкции внутри документов считаются данными. Источник: установленный SDK openai.resources.responses.responses.Responses.parse.

Для семантического режима задайте OPENAI_API_KEY и OPENAI_MODEL=gpt-6-astra в локальном .env либо окружении процесса сервера. Не передавайте ключ через API, CLI-аргумент или Git. .env.example — образец без секретов. Установленное окружение имеет приоритет над .env.

# Сначала заполните OPENAI_API_KEY и OPENAI_MODEL в локальном .env.
$env:ANALYSIS_MODE = 'semantic'
.\.venv\Scripts\python.exe -m uvicorn backend.app:app --env-file .env --host 127.0.0.1 --port 8000

Сначала проверьте доступ проекта минимальным запросом. Затем запустите полный анализ через HTTP (обе команды платные, выполняются отдельно от тестов):

.\.venv\Scripts\python.exe -m scripts.smoke_openai --env-file .env
.\.venv\Scripts\python.exe -m scripts.smoke_api --env-file .env --mode semantic --output artifacts\api-semantic.json

Семантический запрос передаёт извлечённый текст документов в OpenAI с store=False. Для Astra используется reasoning.effort=low; модель возвращает строгую структуру с ID, а Python подставляет оригинальные цитаты. Доступ к модели зависит от API-проекта. Без ключа/модели возвращается HTTP 503; при ошибке нет скрытого переключения на другой режим или модель. CLI поддерживает --mode semantic --env-file .env.

Таймаут обращения к OpenAI — 120 секунд, автоматические повторы отключены. Frontend и HTTP smoke ждут до 150 секунд. Детерминированный путь остаётся доступен через ?mode=deterministic; /api/demo всегда использует его.

Отдельная платная проверка полного браузерного сценария с Astra и локальными DOCX организатора (после npm run build, порт backend 8000 должен быть свободен):

$env:LIVE_SEMANTIC_SMOKE = '1'
npx playwright test --project=live
Remove-Item Env:LIVE_SEMANTIC_SMOKE

Обычный npm run test:e2e использует детерминированный backend и не вызывает OpenAI. Семантическая проверка подтверждает загрузку DOCX, ответ модели, отображение результата/источников и экспорт заключения с NEEDS_REVIEW.

Evidence lock и границы MVP

Каждый источник содержит document, section, точный text и clause_id. Для проверки должны совпасть все четыре поля. Буквенные подпункты получают адрес вида 3.4.а из реального номера родителя и буквы в документе. У текста без номера section=null; такая ссылка не подтверждает вывод. Текст из ячеек таблиц читается в порядке XML документа. Текст изображений не распознаётся.

VERIFIED в MVP используется для наблюдаемого сохранения названия подразделения и точного сохранения функции с явным владельцем в обеих редакциях. Пустая, неверная или нерелевантная ссылка не даёт этот статус. Все интерпретационные findings и семантическое заключение остаются NEEDS_REVIEW, даже если их цитаты существуют: цитата сама по себе не доказывает перенос, потерю, конфликт или дублирование. Отсутствие соответствия в этих документах не доказывает прекращение функции в организации.

Счётчики изменений в summary отражают кандидатов, включая непроверенные. БВА учитывается как родительский блок, поэтому контрольные перечни дают 3 и 5 единиц, включая сам БВА. Извлечённые функции включают записи прав и запретов, помеченные kind. Неявные подразделения, свободная форма полномочий и сложная нумерация могут требовать ручной проверки; ограничения отражены в warnings. Не поддержанные форматы нумерации не реконструируются догадками.

Один запрос обрабатывается синхронно в рабочем потоке. Очереди, БД и внешнего поиска нет. agent_trace — список выполненных стадий в готовом ответе, не поток прогресса и не chain-of-thought. API не сохраняет загруженные документы и результаты постоянно.

Ограничения: 10 MiB на DOCX, 40 MiB суммарного распакованного содержимого на DOCX; семантический payload до 600 000 символов, без молчаливого усечения. Поддерживаются DOCX, не PDF/XLSX/OCR. Сервер MVP предназначен для локального запуска.

API и проверка

Подробный контракт и примеры ошибок: docs/API.md.

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe -m compileall -q backend tests
git diff --check

Дополнительная проверка с локальными документами организатора: требует обе редакции в data/; на чистом клоне без этих файлов её пропустите. Скрипт сам запускает временный сервер и завершает его:

.\.venv\Scripts\python.exe -m scripts.smoke_api --output artifacts\api-comparison.json

Синтетические DOCX создаются тестами в памяти. Тесты реальных редакций запускаются при наличии файлов в data/, иначе пропускаются. OpenAI SDK тестируется через локальный HTTP mock; это не подтверждает доступность модели или качество живого семантического анализа.