KT Neural Document Agent

Нақты OpenAI API қосу: .env.example негізінде жоба түбіндегі .env файлына кілтті енгізіңіз → npm run agent:setup → npm run agent → http://127.0.0.1:8000/. Толhttp:ық нұсқаулық: backend/README.md. Төмендегі npm start және үш файлдық ZIP демо режимін ашады.

HackAlem AI · TheDArk · Қазақтелеком тапсырмасына арналған AI Command Center интерфейсі. Kazakhtelecom стилінен шабыт алған хакатон концепті; ресми өнім емес.

Мәселе және шешім

Қайта ұйымдастыру кезінде құжат редакцияларындағы функциялар жоғалуы, қайталануы немесе жауапкершілік өзгеруі мүмкін. Интерфейс екі редакцияны байланыстырады, өзгерістерді нейрондық картада көрсетеді және әр тұжырымнан құжаттың тармағына өтуге мүмкіндік береді.

Ортасында анимациялық Neural Core, екі жағында Document A/B, төменде Agent командалық жолы орналасқан. Чат тарихының орнына сұрақтың жауабы жеке Agent Insight терезесінде ашылады.

Іске қосу — үш файл жеткілікті

index.html, style.css, script.js файлдарын бір папкада сақтаңыз. index.html файлын браузерде ашыңыз. Демо үшін орнату немесе API кілті қажет емес. VS Code ішінде Live Server арқылы да ашуға болады.

Репозиторийдегі жергілікті серверді Node.js 18+ арқылы іске қосу:

npm start

Нәтиже: http://127.0.0.1:5173. Браузер ескі көріністі сақтаса, Ctrl+Shift+R басыңыз. npm run check JavaScript синтаксисін тексереді. npm тәуелділіктері мен build қадамы жоқ.

Демо жолы

1. «Демо іске қосу» → екі мысал модулі қосылады.
2. «INITIATE INTELLIGENCE» → алты tool кезеңі көрсетіледі.
3. Картада 14 өзгеріс пайда болады: +05 жаңа, −03 жоғалу қаупі, ↻04 өзгерген, ≈02 қайталану.
4. M1 түйінін басыңыз: 3.5-тармақтың екі редакциясы Source Trace ішінде қатар ашылады.
5. ASK THE AGENT жолына «ДИТААД туралы түсіндір» жазыңыз.
6. Ctrl+K / Cmd+K → команда таңдаңыз; ↑/↓ және Enter жұмыс істейді.
7. «Есеп» → JSON, CSV немесе PDF. PDF батырмасы басып шығару терезесін ашады: «PDF сақтау / Басып шығару» → браузерде «Save as PDF» таңдаңыз.

Қосымша: NEW / LOST / TRANSFORMED / OVERLAPS / SOURCE MAP сүзгілері; презентация режимі; анимацияны өшіру; мобильді көрініс; файлдарды сүйреп қосу; талдауды тоқтату және жаңа сессия.

Демо мен нақты талдаудың айырмасы

Әдепкі DEMO_MODE = true. Таңдалған файлдар оқылмайды және серверге жіберілмейді. Кез келген жүктелген жұп үшін №8 → №9 алдын ала дайындалған сценарий көрсетіледі. Upload scanning, tool кезеңдері, 47 функция, 1 184 байланыс, 96% confidence және Document DNA — демонстрация. DNA ғылыми өлшем емес.

3.4, 3.5 және 5.3.2 тармақтарының үзінділері берілген DOCX файлдарымен тексерілген. «Тесттік» тұжырымдар мен «ДЕМО-…» тармақтары жасанды. Үзінділердің түрі Source Trace пен экспортта белгіленген. Құрылымдағы өзгеріс функцияның ресми ауысқанын өздігінен дәлелдемейді.

Интерфейс операциялар күйін көрсетеді; модельдің ішкі ойлау тізбегін көрсетпейді. Еркін сұрақтарға шынайы жауап және құжаттарды өңдеу команданың backend модулінде орындалуы керек.

Архитектура және backend

index.html  → экран құрылымы, диалогтар, қолжетімділік
style.css   → responsive Command Center, core/orbit/scan анимациялары
script.js   → Canvas, күй, демо, карта, Agent Insight, API, экспорт
                     │
                     ├─ DEMO_MODE=true  → жергілікті сценарий
                     └─ DEMO_MODE=false → Agent API
                          POST /api/documents
                          POST /api/analyze
                          POST /api/agent
                          GET  /api/session/:id
                          GET  /api/evidence/:id

Backend қосу үшін script.js басында DEMO_MODE = false, API_BASE = 'http://127.0.0.1:8000' орнатыңыз. Backend CORS пен файл валидациясын баптауы тиіс. server.cjs — тек статикалық сервер, Agent API емес. API келісімі: docs/integration.md.

Қолдау: PDF, DOCX, XLSX; әр редакцияға бір файл, файл көлемі 20 MB-тан аспайды. Клиент кеңейтімді, көлемді және бос файлды тексереді. Мазмұнды backend тексеруі керек. Сұрауларда 120 секунд таймаут бар. Нақты режимде қате шықса, демо жауабына үнсіз ауыспайды. «Күтуді тоқтату» браузер сұрауын үзеді; сервер тапсырмасын жоюға кепіл емес.

API мәтіндері HTML ретінде орындалмайды. CSV формула префикстері қорғалған. API кілттерін frontend-ке салмаңыз. Сессия күйі жадта ғана сақталады; жаңартқанда жойылады. Нақты режимде Settings арқылы сервердің session_id мәнін енгізіп қалпына келтіруге болады. Google Fonts жүктелмесе жүйелік қаріптер қолданылады.

Командадағы бөлініс

• 1-адам: құжаттарды оқу, тармақ/бөлім/функция және дереккөздерді шығару.
• 2-адам: семантикалық салыстыру, Agent API, функцияларды сәйкестендіру және evidence.
• 3-адам: осы интерфейс, README, backend интеграциясы және демо.

Демо жоспары: docs/presentation.md. Тексеру тізімі: docs/demo-checklist.md. Бұрынғы интерфейс legacy/ ішінде сақталған.

---

Backend MVP — команданың құжаттамасы

Hackathon team repository for TheDArk

mvp/
├── app.py                 # Streamlit UI: загрузка документов, отображение результата
├── core/
│   ├── parser.py           # Извлечение текста из .docx / .pdf / .xlsx / .txt
│   └── analyzer.py         # Ядро агента: промпт + вызов Claude API + разбор JSON-ответа
├── data/
│   ├── before_sample.txt   # Тестовый пример "до" (Положение о внутреннем аудите, ред. №8)
│   └── after_sample.txt    # Тестовый пример "после" (ред. №9)
├── requirements.txt
└── .env.example

Поток данных:

1. Пользователь загружает документ «до» и документ «после» (или использует встроенные тестовые примеры).
2. core/parser.py извлекает текст, сохраняя нумерацию пунктов (1.1, 2.3.4 и т.д.) — она нужна модели, чтобы указывать точный источник каждого вывода.
3. core/analyzer.py отправляет оба текста в Claude одним запросом со строгим системным промптом, который требует:
   • определить реорганизованные / сохранённые / созданные подразделения;
   • сопоставить функционал и найти потери функций;
   • найти дублирование функций и потенциальный конфликт интересов;
   • для каждого вывода указать источник (документ + номер пункта);
   • не делать выводов, не подтверждённых текстом.
4. Ответ модели в формате JSON парсится и отображается в app.py: таблицы, раскрывающиеся карточки с источниками, итоговое заключение.

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

# 1. Клонировать репозиторий и перейти в папку
git clone <ссылка на репозиторий>
cd mvp

# 2. Создать виртуальное окружение (рекомендуется)
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

# 3. Установить зависимости
pip install -r requirements.txt

# 4. Указать ключ Anthropic API
cp .env.example .env
# откройте .env и вставьте свой ключ, затем экспортируйте:
export ANTHROPIC_API_KEY=[скрыто]     # Windows (PowerShell): $env:ANTHROPIC_API_KEY="[скрыто]"

# 5. Запустить приложение
streamlit run app.py

Откроется браузер на http://localhost:8501. По умолчанию включены встроенные тестовые примеры — просто нажмите «Запустить анализ», чтобы увидеть результат без загрузки своих файлов.

Тестовый сценарий (тексеру ушын)

В data/ лежат два сокращённых варианта реального Положения о внутреннем аудите — редакция №8 («до») и редакция №9 («после»). Между ними заведомо известны изменения:

• в редакции №9 появились два новых департамента — ДИТААД и ДОА, которых не было в редакции №8 (там была обобщённая роль «Директор направления внутреннего аудита»);
• часть функций и пунктов раздела 5 переформулирована и перераспределена между новыми департаментами.

Агент должен отметить ДИТААД и ДОА как «созданные», ДНМ и ДККМ — как «сохранённые», и указать конкретные пункты (например п. 3.4, п. 5.3.2) как источник каждого вывода.

Статус реализации (must have из задачи)

#	Требование	Статус
1	Определение реорганизованных/сохранённых/созданных подразделений	✅
2	Сопоставление функционала и выявление потери функций	✅
3	Выявление дублирования функций и конфликта интересов	✅
4	Ссылка на источник (документ + пункт) для каждого вывода	✅
5	Итоговое аналитическое заключение в понятном виде	✅

Известные ограничения MVP и возможное развитие

• Сравнение выполняется одним запросом к модели — для более надёжной и проверяемой работы на больших комплектах документов стоит разбить на отдельные шаги (агентный pipeline): (1) извлечение структуры каждого документа отдельно → (2) сопоставление → (3) верификация ссылок на пункты отдельным проверочным вызовом.
• Нет автоматического сопоставления с внешними НПА/стандартами и бенчмаркинга с другими операторами (см. раздел «Опционально» задачи) — следующий шаг развития.
• Для очень больших документов (сотни страниц) потребуется чанкинг и векторный поиск (RAG) вместо передачи полного текста в промпт.
• Выводы ИИ носят рекомендательный характер и требуют проверки ответственным сотрудником (см. раздел «Ограничения» задачи).

Команда

• Deректерді дайындау (парсинг документов): core/parser.py
• Ядро ИИ-агента (сравнение и объяснимость): core/analyzer.py
• Интерфейс и README: app.py, этот файл