TraceGraph — анализ сети денежных переводов

Проект команды hackyou для кейса HackAlem «Граф денег». TraceGraph помогает аналитику понять, кто собирает, распределяет и переводит средства, и выбрать участников для дальнейшей проверки. Результат — направленный граф переводов, гипотезы ролей, сообщества и приоритеты с объяснениями.

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

• Кейсы, загрузка и проверка трёх Parquet-файлов, запуск анализа и история результатов.
• Диаграммы ролей и приоритетов, поиск участников по GID, фильтры и карточки с основаниями выводов.
• Граф входящих и исходящих переводов: направления, суммы, число операций и переходы между участниками. Узлы можно окрашивать по ролям или сообществам; легенда объясняет цвета, отдельная обводка выделяет выбранного участника.
• Гипотезы сообществ с числовыми основаниями: состав ролей, внутренние и внешние потоки, исходные узлы (seed) и границы наблюдения. При отсутствии потоков явно указывается недостаточность данных.
• Три CSV для сдачи и отдельный Excel-файл с русским текстом и точными идентификаторами. JSON сохраняются как внутренний снимок для API, графа и карточек.
• В Python SDK — подробные операции, пошаговые расследования и три локальных аналитических агента. Эти функции SDK пока не подключены к веб-интерфейсу.

Критерии ролей

Роли определяются объяснимыми правилами по структуре, суммам и датам переводов. ML оценивает аномальность для приоритета проверки. Основные условия допуска:

Из допустимых ролей выбирается максимальная сила гипотезы: порог 0,45, для coordinator — 0,60. Разница сил двух гипотез не более 0,08 отмечается как неоднозначность. Это пороги силы признаков, а не role_score: уверенность рассчитывается отдельно с учётом полноты наблюдения. Полные формулы, веса и ограничения — в методике ролей.

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

Нужны Python 3.12, Node.js 22.12+ или 24 LTS и Git. Интернет требуется для установки зависимостей. Docker, API-ключи и отдельный сервер БД не нужны.

Скачайте проект:

git clone https://github.com/BAITC-Hacks/hack-c2a931d4-hackyou.git
cd hack-c2a931d4-hackyou

Windows PowerShell — выполните из корня проекта:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
py -3.12 -m venv .venv-engine
.\.venv-engine\Scripts\python.exe -m pip install -r ml\requirements-lock.txt
.\.venv-engine\Scripts\python.exe -m pip install -e ./ml --no-deps
npm.cmd --prefix frontend ci
.\.venv\Scripts\python.exe scripts\dev.py

Если py недоступна, замените py -3.12 на python версии 3.12. Активация окружений и создание .env не требуются.

python3.12 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt
python3.12 -m venv .venv-engine
.venv-engine/bin/python -m pip install -e ./ml
npm --prefix frontend ci
.venv/bin/python scripts/dev.py

Откройте http://127.0.0.1:5173. Скрипт запускает интерфейс и API вместе; Ctrl+C останавливает оба. Повторный запуск — только последняя команда для вашей ОС.

Кейсы и результаты сохраняются локально в storage/, SQLite и миграции создаются автоматически. Проверка API должна вернуть status: "ok" и engine: "configured". Документация API.

Если проект уже установлен: остановите его через Ctrl+C, выполните git pull --ff-only origin main, повторите команды установки зависимостей для вашей ОС и запустите scripts/dev.py. В частности, для Excel нужен openpyxl из backend/requirements.txt. Установка движка с -e ./ml использует обновлённый код. Обновите страницу браузера. Для новых гипотез сообществ запустите анализ заново: сохранённые результаты не пересчитываются автоматически.

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

1. В интерфейсе нажмите «Новый кейс» и создайте кейс с любым названием.
2. Загрузите три файла из папки data/ репозитория: nodes.parquet, edges.parquet, transactions.parquet. Нажмите «Проверить и сохранить». Во вкладке «Исходные данные» ожидаются 2 248 участников, 3 119 связей и 4 840 операций.
3. Во вкладке «Исследование» нажмите «Запустить анализ» и дождитесь статуса «Готово». В обзоре выберите роль или приоритет, найдите участника по GID и откройте его карточку.
4. Нажмите «Исследовать связи». Отправители расположены слева, получатели — справа. Переключите входящие/исходящие связи и «Цвет узлов» → «По ролям» / «По сообществам»; проверьте легенду. Нажмите сумму для деталей или соседний узел для перехода.
5. В «Обзор и участники» → «Результаты анализа · CSV» скачайте три файла ниже. Для просмотра в таблицах есть отдельная кнопка «Скачать для Excel · .xlsx»: идентификаторы сохраняются как текст, без потери цифр. В clusters.csv проверьте гипотезы и суммы потоков; в top_nodes.csv — ранги и объяснения.
6. Обновите страницу: кейс и результат должны сохраниться. Откройте прежний анализ из истории.

Шесть JSON рядом с CSV — внутренний снимок анализа для графа, карточек, операций и восстановления. Они сохраняются на диске и доступны API, но скрыты из списка пользовательских скачиваний. Для обязательной сдачи нужны три CSV, Excel — удобная копия этих таблиц.

Контрольный прогон исходной выборки с IsolationForest и стандартным seed 42 дал 2 248 участников, 91 сообщество, 2 248 ранжированных строк за 7,71 с внутри движка. Для воспроизведения используйте команду CLI ниже с --input data: три CSV создаются при запуске. Autoencoder может дать другие приоритеты; выбранный backend отражается в отчёте запуска.

Для короткой проверки на полностью вымышленных данных используйте три Parquet из synthetic-demo/: ожидаются 38 участников, 37 связей и 96 операций. Подробная сверка с требованиями — в аудите готовности.

Проверка только движка, без интерфейса и API, после установки выше:

.\.venv-engine\Scripts\python.exe -m tracegraph_ai --input synthetic-demo --output out-demo --model isolation_forest

На Linux/macOS замените путь к Python на .venv-engine/bin/python. Ожидаются 5 сообществ и 3 CSV + 6 JSON в out-demo/. Для исходной выборки замените --input synthetic-demo на --input data. Флаг --model isolation_forest явно выбирает лёгкую модель; без него движок автоматически использует доступный backend.

Что уже проверено: чистый запуск платформы, загрузка через API, анализ и восстановление результата; сборка интерфейса; адресные тесты гипотез и совместимости снимков. Полный SDK-прогон исходной выборки с Autoencoder занимал 19,56 с; финальный синтетический прогон с IsolationForest — 0,42 с внутри движка, без установки зависимостей и запуска Python. Это локальные замеры, время на другом компьютере может отличаться. Методика, сравнение ролей и ограничения — в отчёте качества; границы выполненных проверок — в аудите готовности.

Технологии и архитектура

React / TypeScript → FastAPI → отдельный процесс TraceGraph AI
                        ↓                  ↓
                 SQLite + файлы      граф и ML на CPU

Backend и движок используют отдельные Python-окружения. Расчёты выполняет движок; API проверяет и сохраняет результаты, интерфейс показывает их аналитику.

Для масштаба около миллиона узлов потребуется обработка данных частями, очередь фоновых расчётов, приближённые графовые метрики и выдача окрестностей по запросу. Это направление развития; текущий прототип на таком объёме не проверен. Подробнее — архитектура.

Данные, внешние сервисы и ограничения

• В data/ находится обезличенная выборка организаторов HackAlem: узлы, связи и операции за июль 2026 года.
• После установки решение работает локально, без LLM и внешних API. Демонстрация доступна по локальному адресу выше.
• Роли и приоритеты — гипотезы для проверки, а не доказательство нарушения. role_score показывает поддержку роли по наблюдаемым признакам в диапазоне 0–1; это не accuracy и не вероятность нарушения. Разметки подтверждённых ролей в данных нет.
• Данные ограничены одним банком, исходящим обходом до четырёх шагов, порогом 5 000 ₸ и точностью дат до дня. Связи не доказывают движение одних и тех же денег.
• На графе показываются до 6, 12 или 20 соседей по выбранному лимиту; итоги участника учитывают всё окружение.
• Это локальный MVP без авторизации и разграничения доступа, рассчитанный на один процесс API.

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