SAN.AI

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

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

Проект создан для кейса HackAlem AI по анализу организационной структуры и функционала. В текущем продукте отдельно зафиксирован контекст кейса АО «Казахтелеком».

---

1. Какую проблему решает проект

При реорганизации компании изменения распределены по положениям, оргструктурам, должностным инструкциям, приказам и приложениям. Ручное сравнение таких документов занимает время и создаёт риск пропустить:

• функцию, которая исчезла после реорганизации;
• функцию, которая перешла другому подразделению;
• дублирование ответственности;
• потенциальный конфликт функций;
• изменение структуры, которое неочевидно из формулировок документов.

SAN.AI превращает два комплекта документов в сопоставимые модели организации и показывает не только что изменилось, но и на каких фрагментах документов основан вывод.

---

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

Документы ДО / ПОСЛЕ

• загрузка нескольких документов в каждый комплект;
• поддержка DOCX, PDF и XLSX;
• локальное хранение файлов на сервере;
• сохранение координат источника: абзац DOCX, страница PDF, лист и ячейки XLSX;
• обработка ошибок чтения без потери исходного файла.

AI-извлечение

• извлечение организационных сущностей и функций через OpenAI Responses API;
• классификация организационных сущностей как подразделение / должность / неизвестный тип;
• извлечение обязанностей, прав и запретов;
• сохранение условий, области функции и типа ответственности;
• проверка цитат: ссылка AI принимается только если подтверждается исходным разобранным документом;
• сохранение и повторное использование успешного результата;
• фоновая обработка, прогресс и отмена задачи.

Canonical Organization

Из результатов извлечения строится единая модель организации:

• подразделения;
• должности;
• функции;
• владельцы функций;
• иерархические связи, когда они подтверждены;
• источники каждого факта;
• отдельные состояния BEFORE/current и AFTER/proposed.

Версия ПОСЛЕ не становится автоматически утверждённой организацией.

Сравнение ДО / ПОСЛЕ

Comparison engine сопоставляет организационные сущности и функции и формирует findings:

• Сохранено;
• Передано;
• Возможно потеряно;
• Дублирование;
• Потенциальный конфликт.

Для каждого обоснованного вывода сохраняются ссылки на исходные фрагменты документов. Если данных недостаточно или модель вернула непроверяемые ссылки, система не подменяет неизвестность нулём: результат помечается как требующий проверки, а выводы о потерях ограничиваются.

Рекомендации

На основе findings система формирует advisory-рекомендации, например:

• уточнить владельца функции;
• устранить пересечение ответственности;
• проверить потенциально потерянную функцию;
• разделить потенциально несовместимые обязанности.

Рекомендации не изменяют организацию автоматически и требуют проверки ответственным сотрудником.

Интерфейс

Основная навигация: Документы → Структуры → Результаты. На итоговом экране — вкладки Изменения / Рекомендации. Возврат сохраняет результаты; изменение комплекта требует обновления структур. Tutorial открывается только вручную.

В текущем приложении доступны:

• загрузка документов ДО / ПОСЛЕ;
• отображение распознанной структуры;
• режимы Схема / Список;
• просмотр source evidence;
• запуск сравнения;
• findings и рекомендации;
• повторный запуск неполного анализа.

---

3. Основной пользовательский сценарий

1. Пользователь загружает документы ДО изменений.
2. Загружает документы ПОСЛЕ изменений.
3. Система извлекает подразделения, должности, функции и источники.
4. Пользователь проверяет распознанную структуру.
5. SAN.AI сопоставляет две версии.
6. Пользователь получает ключевые изменения и потенциальные риски.
7. Любой существенный вывод можно раскрыть до исходной цитаты.
8. Система показывает рекомендации для последующей проверки человеком.

Ключевой принцип продукта:

Документы → Структуры → Сравнение → Evidence → Рекомендации

---

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

Документы ДО / ПОСЛЕ
        │
        ▼
DOCX / PDF / XLSX parsers
        │
        ▼
Source Fragments
текст + координаты источника
        │
        ▼
OpenAI Structured Extraction
        │
        ▼
Canonical Organization
units / positions / functions / sources
        │
        ▼
Organization Comparison
matching + risk analysis
        │
        ▼
Findings
preserved / transferred / lost / duplicated / conflict
        │
        ├──────────────► Evidence
        │                точные цитаты ДО / ПОСЛЕ
        ▼
Recommendations
        │
        ▼
Web UI

AI используется для смыслового извлечения и сопоставления. Проверка ссылок, ограничения полноты, хранение, состояние current/proposed и публикация результата контролируются серверной логикой.

---

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

Frontend и backend

• Next.js 16
• React 19
• TypeScript 6
• Next.js App Router и Route Handlers
• Lucide React

AI

• OpenAI Responses API
• Structured Outputs / JSON Schema
• модель по умолчанию: gpt-4.1-mini
• API-ключ используется только на сервере

Обработка документов

• DOCX: собственный parser на основе ZIP/XML
• PDF: unpdf / PDF.js
• XLSX: fflate + fast-xml-parser

Данные и хранение

• PGlite для локального PostgreSQL-совместимого режима;
• опционально обычный PostgreSQL через pg;
• документы и результаты анализа сохраняются в файловом storage;
• synthetic organizational dataset и графовые компоненты остаются в проекте как отдельный исследовательский стенд.

Визуализация структуры

• Sigma.js
• Graphology

---

6. Архитектура проекта

Основные части репозитория:

Путь	Назначение
src/app/	страницы приложения и HTTP API
src/components/	пользовательский интерфейс
src/lib/server/	parsers, storage, AI transport, extraction, comparison
src/lib/canonical-organization.ts	преобразование extraction в canonical organization
src/lib/extraction.ts	типы результатов извлечения
docs/DATA_CONTRACT.md	общий контракт данных
docs/EXTRACTION.md	логика AI-извлечения
docs/COMPARISON.md	логика сравнения ДО / ПОСЛЕ
docs/API.md	HTTP API
docs/PRODUCT_SPEC.md	актуальная продуктовая спецификация
tests/	автоматические тесты

Разделение ответственности

Document Intelligence

file -> parser -> source fragments -> AI extraction -> verified sources -> canonical organization

Organization Audit

canonical BEFORE + canonical AFTER -> matching -> findings -> evidence -> recommendations

Такой контракт позволяет развивать два блока независимо, не теряя traceability до исходных документов.

---

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

Требования

• Node.js 22+
• рекомендованная версия из .nvmrc: 22.23.2
• npm
• OpenAI API key для живого AI-анализа

1. Клонировать репозиторий

git clone https://github.com/BAITC-Hacks/hack-8c2d1c68-san-ai.git
cd hack-8c2d1c68-san-ai

Репозиторий HackAlem может быть приватным, поэтому GitHub-аккаунт должен иметь к нему доступ.

2. Установить зависимости

npm ci

3. Создать локальное окружение

cp .env.example .env.local

Добавить в .env.local:

OPENAI_API_KEY=your_key_here
OPENAI_EXTRACTION_MODEL=gpt-4.1-mini
OPENAI_COMPARISON_MODEL=gpt-6-sol

Не публикуйте API-ключ в GitHub.

Для локального режима остальные значения можно оставить по умолчанию:

DATABASE_URL=
PGLITE_DATA_DIR=.data/pglite
DOCUMENT_STORAGE_DIR=.data/documents

4. Запустить приложение

npm run dev

Открыть:

http://127.0.0.1:3000

Опционально: synthetic organizational dataset

Для отдельного графового стенда можно заполнить локальную БД:

npm run db:seed

В локальном режиме PGlite рассчитан на один процесс. Перед db:seed или db:migrate остановите работающий dev/server process.

---

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

Основной сценарий для жюри

Подготовьте два организационных документа или два комплекта документов:

• версия ДО;
• версия ПОСЛЕ.

Подойдут DOCX, текстовый PDF или XLSX.

1. Запустите приложение.
2. Добавьте документы в комплекты ДО и ПОСЛЕ.
3. Нажмите «Построить структуры».
4. Проверьте распознанную структуру и source evidence.
5. Нажмите «Сравнить ДО и ПОСЛЕ».
6. Откройте раздел ключевых изменений.
7. Проверьте один из findings:
   • сохранённая функция;
   • переданная функция;
   • возможная потеря;
   • дублирование;
   • потенциальный конфликт.
8. Откройте evidence и убедитесь, что вывод связан с конкретными цитатами из документов.
9. Откройте вкладку «Рекомендации».
10. Вернитесь к структурам, затем к документам. Добавьте или уберите файл и нажмите «Обновить структуры».

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

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

npm test
npm run typecheck
npm run lint
npm run build

Проверка frontend P0

На Node.js 22.23.2 прошли 77 тестов, TypeScript, ESLint, production build и 4 браузерных сценария. Браузерные тесты используют синтетические API-ответы без внешних AI-вызовов. Отдельно через настоящий API проверены реальная загрузка DOCX и сохранённые редакции 8/9; их анализ остаётся частичным.

npm run build
npm start -- --port 3014
# В другом терминале:
npx playwright install chromium
npm run test:ux

Для другого сервера: UX_TEST_URL=http://127.0.0.1:3000 npm run test:ux. Полная матрица DoD, ограничения и передача разработчикам: UX_REDESIGN_HANDOFF.md.

Smoke-check OpenAI

Проверка соединения и Structured Outputs на синтетических данных:

npm run ai:check

Проверка AI extraction на синтетическом документе:

npm run ai:check-extraction

Проверка comparison engine на синтетическом наборе:

npm run ai:check-comparison

Эти команды делают реальные API-вызовы и требуют OPENAI_API_KEY.

---

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

Входные данные

Система работает с предоставленными пользователем организационными документами:

• положения;
• организационные структуры;
• должностные инструкции;
• распорядительные документы;
• приложения;
• другие внутренние нормативные документы.

Поддерживаемые форматы текущей версии:

• DOCX;
• текстовый PDF;
• XLSX.

OpenAI

Текст выбранных документов передаётся на серверный OpenAI API для structured extraction и смыслового сравнения.

В запросах используется store: false. API key не передаётся в браузер и не должен храниться в Git.

Хранение

По умолчанию документы и результаты анализа сохраняются локально в:

.data/documents

Путь можно изменить через DOCUMENT_STORAGE_DIR.

PostgreSQL

По умолчанию используется PGlite. Для обычного PostgreSQL можно задать:

DATABASE_URL=postgresql://...

---

10. Известные ограничения

Текущая версия является hackathon MVP.

• Выводы AI носят рекомендательный характер и требуют проверки ответственным сотрудником.
• Полнота исходного комплекта документов не может быть доказана автоматически.
• Если часть данных не подтверждена источниками, система ограничивает соответствующие выводы.
• OCR для сканированных PDF не реализован: PDF должен содержать текстовый слой.
• Старые форматы .doc и .xls не поддерживаются.
• Формулы XLSX не вычисляются, используется сохранённое значение.
• Автоматическая нормализация всех сокращений и вариантов названий ограничена.
• Сложные сценарии слияния и разделения нескольких подразделений требуют дополнительной проверки.
• Авторизация и multi-tenant разграничение доступа не реализованы.
• Файловое storage рассчитано на текущий серверный MVP, а не на production multi-instance deployment.
• Workforce Alignment, 1C/SAP/HRIS и автоматическая работа с сотрудниками относятся к дальнейшему развитию продукта и в текущий MVP не входят.
• Recommendations не изменяют current organization автоматически.
• Нулевое число findings не является доказательством отсутствия организационных рисков.

---

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

Тестовый стенд NVIDIA Brev:

https://3000-ynr8e39a4.gobrev.dev/

Доступ может требовать входа в разрешённый NVIDIA/Brev аккаунт.

Важно: GitHub Actions организации в текущий момент не запускаются из-за зафиксированной в репозитории billing-блокировки, поэтому автоматическая доставка последнего main на Brev не гарантируется. Для проверки актуального состояния проекта используйте локальный запуск из текущего репозитория.

---

12. Безопасность

• не коммитьте .env.local;
• не публикуйте OPENAI_API_KEY;
• не передавайте реальные корпоративные документы в публичные репозитории;
• перед использованием конфиденциальных данных проверьте внутренние правила компании и допустимость передачи данных внешнему AI-сервису.

---

13. Полезная документация проекта

• Требования кейса
• Product Spec
• Data Contract
• Document Extraction
• Comparison Engine
• HTTP API
• UX Redesign Spec
• Frontend redesign: DoD и передача работы

---

Команда

SAN.AI

HackAlem AI, 2026

Раздельные модели AI

Извлечение: OPENAI_EXTRACTION_MODEL, затем прежний OPENAI_MODEL, затем gpt-4.1-mini. Сравнение: OPENAI_COMPARISON_MODEL, по умолчанию gpt-6-sol. Для GPT-6 Sol/Astra/Luna сравнение отправляет reasoning.effort: low; для gpt-4.1-mini reasoning не передаётся. Возврат сравнения к прежней модели: OPENAI_COMPARISON_MODEL=gpt-4.1-mini. После изменения окружения перезапустите сервер. Таймаут одного запроса остаётся 90 секунд, всего сравнения — 10 минут. Кэш сравнения учитывает модель и версию алгоритма. Кэш извлечения сохраняется: смена модели не запускает повторную обработку документов автоматически. На Brev окружение хранится в /home/ubuntu/workspace/san-ai/.env.local; релизы используют ссылку на этот файл. Сначала доставьте обновлённый код. Перезапуск существующего сервиса: sudo systemctl restart san-ai.