AML Graph

Локальная система анализа графа транзакций для первичного AML-скрининга. Проект помогает аналитику быстро увидеть связи между счетами, выделить структурные роли и приоритетные узлы, исследовать сообщества и получить объяснимые гипотезы для дальнейшей проверки.

Система работает с наблюдаемыми внутрибанковскими переводами из Parquet-файлов и не подменяет расследование доказательством нарушения.

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

• построение ориентированного графа счетов и переводов;
• расчёт метрик входящих и исходящих потоков, степеней, контрагентов, глубины и компонентов связности;
• назначение структурных ролей: coordinator, consolidator, distributor, transit, terminal, peripheral;
• объяснение каждой роли текстовым evidence;
• расчёт нормированного priority_score по наблюдаемому объёму потоков;
• воспроизводимое выделение кластеров алгоритмом Louvain;
• анализ временных и структурных сигналов: транзитное совпадение в окне 48 часов, всплески активности, синхронные входящие операции, повторяющиеся маршруты и суммы, циклы длины 2–3, выбросы по глубине;
• интерактивный граф на React и Canvas: поиск, масштабирование, панорамирование, фильтры кластеров, просмотр соседей, история навигации и карточка узла;
• симуляция устойчивости топологии при удалении топ-N узлов;
• экспорт nodes_roles.csv, clusters.csv и top_nodes.csv;
• локальный русско-английский интерфейс;
• опциональный AI-ассистент для вопросов по результатам анализа. Ассистент получает ограниченные извлечённые фрагменты данных, цитирует gid и хранит историю локально в SQLite.

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

1. Пользователь помещает nodes.parquet, edges.parquet и transactions.parquet в одну папку.
2. Pipeline проверяет обязательные поля, приводит типы и исключает связи с неизвестными узлами и петли.
3. Из узлов и агрегированных рёбер строится ориентированный граф NetworkX.
4. Для каждого узла рассчитываются потоки и структурные показатели, затем применяются правила ролей и приоритизации.
5. Внутри компонентов связности строятся взвешенные сообщества Louvain, после чего формируются CSV-выгрузки и сигналы по сырым транзакциям.
6. В веб-интерфейсе аналитик запускает анализ, изучает обзор графа или конкретный узел, фильтрует сообщества и скачивает результаты. При наличии API-ключа можно задать вопрос AI-ассистенту.

Технологии

• Python 3.12+;
• FastAPI и Uvicorn — локальный API и раздача собранного интерфейса;
• pandas и PyArrow — обработка таблиц и Parquet;
• NetworkX 3.7 — ориентированный граф, компоненты связности и Louvain;
• React 19, Vite 6 и JavaScript — интерфейс;
• Canvas и Web Worker — визуализация и расчёт layout графа;
• OpenAI Python SDK и Responses API, модель по умолчанию gpt-5.4-nano — только для опционального ассистента;
• SQLite — локальная память диалогов;
• python-dotenv — чтение .env.

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

Parquet-вход
    │
    ▼
src/aml_graph/io.py ──> graph.py ──> analysis.py ──> roles.py
                                      │                 │
                                      ├──> clustering.py ──> exports.py
                                      └──> patterns.py
                                                            │
                         run_pipeline.py (CLI)              │
                                │                            │
                                └────────────── app.py (FastAPI)
                                                             │
                              frontend/src (React + Canvas) ◄─┘
                                                             │
                         OpenAI API (только чат, опционально)

• run_pipeline.py запускает пакетный анализ и сохраняет CSV в указанную папку.
• app.py предоставляет /api/analyze, экспорт, карточки узлов, resilience и chat API, а также отдаёт frontend/dist.
• src/aml_graph/ содержит загрузку, анализ, роли, кластеры, сигналы, экспорт и AI retrieval.
• frontend/ содержит интерфейс и тесты браузерного сценария.
• entryset/ содержит пример входного набора, outputset/ — результаты пакетного запуска.

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

Требуются Python 3.12+ и Node.js 22+.

python -m pip install -r requirements.txt

if (!(Test-Path .env)) { Copy-Item .env.example .env }

cd frontend
npm ci
npm run build
cd ..

python app.py

Откройте http://127.0.0.1:8000 и нажмите Run analysis. По умолчанию веб-приложение читает entryset/. В поле папки можно указать другой каталог на Python-сервере, если в нём есть все три Parquet-файла.

Для пакетного режима без веб-интерфейса:

python run_pipeline.py --input entryset --output outputset

Для разработки интерфейса запустите python app.py в одном терминале и npm run dev из frontend/ в другом. Vite проксирует /api на 127.0.0.1:8000.

AI-ассистент не обязателен для основного анализа. Чтобы включить его, укажите ключ в локальном .env:

OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-5.4-nano

Файл .env игнорируется Git и не должен содержать ключ в коммите. Без ключа анализ графа и остальные функции продолжают работать, но чат недоступен.

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

Повторяемый сценарий для жюри:

1. Выполнить установку и сборку выше.
2. Запустить python app.py.
3. Открыть http://127.0.0.1:8000, оставить entryset и нажать Run analysis.
4. Найти gid через поиск или выбрать строку рейтинга.
5. Открыть карточку узла, посмотреть роль, доказательство, потоки, сигналы и предложенные запросы данных.
6. Переключить кластерный фильтр, изменить направление обхода и масштаб графа.
7. Скачать три CSV через интерфейс.

Проверка API:

Invoke-RestMethod http://127.0.0.1:8000/api/health
Invoke-RestMethod -Method Post http://127.0.0.1:8000/api/analyze -ContentType 'application/json' -Body '{}'

Документация API доступна по http://127.0.0.1:8000/api/docs.

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

python -m unittest discover -s tests -v
cd frontend
npm test
npm run build

Браузерные smoke-тесты требуют запущенного сервера и установленного Microsoft Edge:

node tests/browser.mjs
node tests/seeds.mjs
node tests/features.mjs
node tests/clusters.mjs

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

Входная папка должна содержать:

• nodes.parquet: gid, depth, is_seed;
• edges.parquet: src, dst, sum_kzt, n_tx, depth;
• transactions.parquet: src, dst, date, sum_kzt.

В репозитории есть пример entryset/. В текущем наборе pipeline проверяет 2 248 узлов, 81 seed и 444 узла на границе глубины 4; эти значения пересчитываются при запуске и не зашиты в код.

Внешняя интеграция только одна: при включённом AI-ассистенте сервер отправляет в OpenAI ограниченные контексты и результаты локального retrieval. API-ключ остаётся на сервере. Проверка соединения (/api/chat/check) выполняет отдельный небольшой запрос без данных графа. Основной анализ, визуализация и экспорты выполняются локально.

Ограничения

• Анализ использует только наблюдаемые внутрибанковские переводы из входного набора; внешние поступления, операции ниже порога 5 000 KZT, балансы, клиентские атрибуты и назначение платежа отсутствуют.
• Входящие потоки seed-узлов неполны, а узлы глубины 4 без исходящих рёбер могут быть обрезанной границей графа, а не настоящими терминальными узлами.
• Роли и priority_score — объяснимые правила и сортировка наблюдаемого объёма, а не вероятность нарушения, баланс или доказательство вины.
• Сигналы временной совместимости не доказывают, что перемещались те же деньги; resilience описывает только статическую топологию.
• Приложение рассчитано на одного локального аналитика, слушает loopback, не имеет аутентификации и многопользовательской изоляции запусков.
• Результаты и память чата локальны; AI-чат зависит от наличия ключа, доступа к выбранной модели, квоты и сети.
• Граф и расчёты выполняются в памяти; полноценное масштабирование до очень больших графов в текущей версии не реализовано.

Deployed-версия

В текущем репозитории подтверждённой ссылки на deployed-версию нет. Приложение запускается локально по адресу http://127.0.0.1:8000.

Выходные файлы

• nodes_roles.csv — строка на каждый узел: роль, scores, кластер и объяснение;
• clusters.csv — размер, seed-узлы, внутренний объём, top-узлы и гипотеза кластера;
• top_nodes.csv — ранжированные кандидаты для первичного просмотра и причина попадания в список.