Граф денег · EmbeddedAi

Инструмент для AML-аналитика: восстанавливает наблюдаемую структуру сети переводов, объясняет роли узлов и помогает выбрать приоритеты дальнейшей проверки. Версия приложения — 0.8.0, правила — 2.2.

Демо: https://cca8f159.nip.io — открывается на явно обозначенном синтетическом наборе. Для анализа официальных данных загрузите три Parquet-файла локально. Роли — проверяемые гипотезы, а не утверждения о виновности.

Для жюри: три файла на вход → три CSV на выход

В корне есть analyze.py — отдельный Python-скрипт. Он вызывает тот же расчёт, что CLI и веб-интерфейс. Node.js, браузер, API-ключи и сервер для получения CSV не нужны. В приватном репозитории уже есть официальный набор data/data/.

Единственная команда пайплайна для жюри — из корня репозитория, одинаковая на Windows, macOS и Linux:

uv run --frozen --no-dev python analyze.py --data ./data/data --out ./artifacts

Команда сама создаёт окружение, устанавливает закреплённые зависимости, читает исходные Parquet, рассчитывает результат, записывает и проверяет все три CSV. Ручной подготовки данных, запуска сервера и отдельного экспорта нет. Единственный предварительно необходимый инструмент — uv; Python 3.12 при необходимости установит uv. При уже установленном окружении доступен полностью офлайн-запуск, описанный в RUNNING.md.

Установите uv, если его нет:

Linux / macOS, терминал:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows, PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

После установки откройте новый терминал, перейдите в корень клонированного репозитория и выполните единственную команду пайплайна выше.

uv создаёт .venv, при необходимости загружает Python 3.12, устанавливает зависимости из uv.lock и запускает расчёт. Интернет нужен при первой установке; после неё вычисления выполняются локально. На официальном наборе ожидаются 2248 строк узлов, 88 сообществ и TOP 50. Актуальные фактические проверки — VALIDATION_08.md. Сверка всех обязательных и дополнительных пунктов — AUDIT_MUST_HAVE.md.

Можно передать три файла по отдельности, в том числе с другими именами и из разных каталогов. Эта команда также одинакова для PowerShell, Bash и zsh:

uv run --frozen --no-dev python analyze.py --nodes "data/data/nodes.parquet" --edges "data/data/edges.parquet" --transactions "data/data/transactions.parquet" --out "artifacts"

Используйте либо --data, либо все три аргумента файлов. Справка:

uv run --frozen --no-dev python analyze.py --help

Обычный CLI сохранён: uv run --frozen --no-dev money-graph analyze --data ./data/data --out ./artifacts. После установки пакета доступны money-graph и python -m money_graph. Пошаговые команды установки, вариант без uv через pip, запуск на трёх ОС и разбор ошибок — RUNNING.md.

Файл	Обязательные поля
nodes_roles.csv	gid, role, role_score, cluster_id, priority_score, evidence
clusters.csv	cluster_id, n_nodes, n_seed, sum_kzt_internal, top_gids, hypothesis
top_nodes.csv	rank, gid, role, priority_score, why

Дополнительно создаются report.html (самостоятельный офлайн-отчёт со всеми узлами, поиском, фильтрами, ролями и кластерами), run_report.json (параметры, SHA-256 источников и время) и result.json (состояние для API). Откройте report.html двойным щелчком: установка Node.js, сервер и интернет для его просмотра не нужны. Возможности и ограничения отчёта. CSV записаны в UTF-8 с одинаковыми переносами строк на всех ОС; int64 ID — точные десятичные строки. При чтении в Excel/pandas задавайте для gid текстовый тип, чтобы потребитель не округлял идентификаторы.

Код завершения 0 и JSON status: "success" в stdout означают, что все три CSV записаны и проверены: точный порядок колонок, число строк и заполненность. JSON содержит output_dir, список exports с путями, схемами, количеством строк и SHA-256, report_html с путём и SHA-256 HTML, а также total_runtime_seconds до окончания проверки файлов. Установка зависимостей не входит в это поле; отдельный внешний замер включает запуск Python. Все численные результаты вычисляются заново по переданным файлам. Для наборов меньше 20 узлов TOP содержит все доступные узлы без выдуманных строк. Некорректные аргументы, данные или пути дают 2, диагностику в stderr и сохраняют прежнюю выгрузку. --out допускает новую/пустую папку либо папку только с результатами приложения; CLI защищает исходники и посторонние файлы от перезаписи. Исходный набор и artifacts/ предназначены для жюри в рамках хакатона, не для публичного размещения.

Проверка выгрузок и материалы для показа

Независимая сверка всех строк CSV с исходными Parquet, кластерами, рейтингом и SHA-256 файлов — без повторного расчёта ролей:

uv run --frozen --no-dev python scripts/check_submission.py --out artifacts --data data/data

Проверка сохранённых выгрузок без Parquet-библиотек: python scripts/check_submission.py --out artifacts (на Linux/macOS системная команда может называться python3). При успехе — JSON и код 0; при нарушении контракта — диагностическое сообщение и код 2.

• Один слайд: данные → метрики → роли → интерфейс.
• Сценарий живого демо на пять минут.
• Три разбора узлов с численными порогами.
• Описание для платформы и полная матрица соответствия.

Карточка любого названного жюри узла доступна без браузера и AI:

uv run --frozen --no-dev python scripts/demo_nodes.py --result artifacts/result.json --gid 100000003684369100

Можно повторить --gid до 20 раз и добавить --out output/cards для сохранения отдельных Markdown-файлов. Идентификатор в примере выбран только для демо; расчёт обрабатывает все переданные узлы.

Подготовленный локальный пакет для жюри: output/money-graph-submission.zip. Он включает исходники, официальный набор, готовый интерфейс и материалы показа; manifest.json содержит SHA-256 каждого файла. Сам ZIP не хранится в Git. Для повторной упаковки уже подготовленного комплекта:

uv run --frozen --no-dev python scripts/package_submission.py

Команда ожидает свежие artifacts/, сборку web/dist и дополнительные материалы в output/submission/ (PDF, START_HERE и минимум две карточки). Эти локальные материалы уже включены в готовый ZIP; для обычного расчёта из checkout упаковщик не нужен.

Проверить расчёт без веб-зависимостей

uv run --frozen python scripts/verify.py --backend-only

Команда устанавливает зафиксированные dev-зависимости, проверяет Python lint, форматирование, типы и тесты, включая официальный контракт. Node.js и Chromium для этой команды не требуются. Полная проверка с интерфейсом:

uv run --frozen python scripts/verify.py

Полный вариант дополнительно требует Node.js 22.12+ с npm, собирает frontend, проверяет TypeScript/Biome, production API/CSV и браузерные сценарии Playwright. На Linux библиотеки Chromium можно установить командой npm --prefix web exec -- playwright install --with-deps chromium после npm --prefix web ci. Подробности и диагностика — RUNNING.md.

GitHub CI отключён по решению владельца; автоматических запусков на push/PR нет. Проверки выполняются командами выше локально. Сохранённая матрица ОС может быть включена вручную позже. Подготовленные инструкции Windows/macOS не выдаются за выполненные тесты на этих ОС; фактические проверки перечислены в VALIDATION_08.md.

Открыть веб-интерфейс

Установите Node.js версии 22.12+ вместе с npm. Из корня репозитория на Windows/macOS/Linux:

uv run --frozen --no-dev python scripts/start.py --data ./data/data --port 3010

Откройте http://127.0.0.1:3010. Скрипт устанавливает зависимости из lockfiles, собирает интерфейс и запускает приложение. Для синтетического примера опустите --data. При последующих запусках уже собранного приложения достаточно:

uv run --frozen --no-dev money-graph serve --data ./data/data --port 3010

Bash-обёртки scripts/start.sh и scripts/verify.sh сохранены для совместимости; на Windows Bash не нужен. Порт меняется через --port или PORT. Все JS/CSS включены в сборку; CDN и внешние шрифты не используются. Дополнительный AI-ассистент обращается к OpenAI только при явно отправленном вопросе; остальные функции работают без API-ключей и платных сервисов.

Что можно проверить в интерфейсе

• Направленный граф со стрелками, точный поиск gid, фильтры и шесть ролей.
• Метрики, объяснение роли, поддержка правила до/после поправки наблюдаемости.
• PageRank, точное посредничество на официальном наборе, охват seed, Louvain.
• Учёт 444 узлов на границе, изолятов, неполного входа seed и самопереводов.
• Дневные потоки, сопоставление через 1–2 дня, пути от seed, циклы и звенья A→B→C.
• Всплески активности относительно собственной медианы, поступления от ≥3 плательщиков за день и повторные малые суммы относительно Q1. Видны формальные пороги, размер выборки и отказ от оценки при недостатке данных; это поводы для проверки, не доказательство дробления.
• Необычные профили относительно того же колена: контрагенты и денежный объём, с численным порогом, размером группы сравнения и явным отказом при нехватке данных.
• 12 сценариев чувствительности весов; сравнение удаления top-N, degree и случайных узлов.
• Выгрузки CSV, справка узла с SHA-256 и экспорт графа в PNG.
• Светлая, тёмная и системная темы с сохранением выбора; граф и диаграммы следуют теме.
• Сохранение выбранного расчёта после обновления страницы и перезапуска сервиса.
• Полная очередь всех узлов с фильтрами, сортировкой и исходным глобальным рангом; выбор до 20 узлов, локальные заметки и выгрузка перечня на проверку.
• Диагностика устойчивости ролей к 16 вариантам порогов и сообществ к seed/resolution Louvain; отдельные показатели по узлам TOP 20. Методика.
• AI-аналитик над графом: понимает вопросы и продолжения разговора, учитывает карточку, выбранную группу, фильтры и текущую страницу очереди. Сам выбирает проверки, сравнивает узлы, объясняет результаты и предлагает переходы к карточкам.
• Раскладка графа в Web Worker; повторные API-запросы используют проверенный кеш расчёта с обнаружением изменения или удаления файла.

Посмотреть тёмную тему · AI-аналитик над графом.

Основной сценарий: загрузите три файла → откройте TOP → объясните роль через факты → найдите произвольный gid → покажите связи/сообщество → скачайте CSV. Кнопка «Пути, циклы и хронология» открывает свидетельства, вкладка «Проверки» — чувствительность и удаление узлов. Подробнее: демо, аудит всех требований, проверки 0.8. История проверок: 0.7, 0.6, 0.5, 0.4, 0.3.

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

flowchart LR
    P[Три Parquet] --> V[Валидация схемы и сумм]
    V --> G[Направленный граф NetworkX]
    V --> T[Дневные потоки и временные признаки]
    G --> M[Метрики и ограничения наблюдения]
    T --> R
    M --> R[Роли, Louvain и приоритеты]
    M --> F[Профили относительно колена]
    R --> C[Три CSV + офлайн HTML]
    R --> S[Чувствительность рейтинга]
    G --> E[Пути, циклы и удаление top-N]
    R --> A[FastAPI]
    E --> A
    S --> A
    F --> A
    A --> U[TypeScript + Cytoscape.js]
    Q[Вопрос + контекст + история] --> L[OpenAI: выбор проверок и объяснение]
    L --> D[Проверка аргументов + вычисление по графу]
    A --> D
    D --> L
    D --> U
    L --> U
    X[Caddy / HTTPS] --> A

Python 3.12, pandas, PyArrow, NumPy/SciPy, NetworkX, FastAPI, Uvicorn; TypeScript, Cytoscape.js и Vite. CLI и API вызывают один pipeline.analyze. Состояние хранится в каталогах запусков; база данных для данного объёма не нужна. Основной аналитический пайплайн выполняется на CPU. GPU, обучение нейросети и платные API для него не требуются.

uv build --wheel собирает самостоятельный Python-пакет для команд demo и analyze. Правила включены в wheel: после установки расчёт работает вне checkout без --rules. Исходные данные и собранный веб-интерфейс в wheel не включены. Для веб-приложения используйте checkout и scripts/start.py.

Объяснимые правила

Правила версии 2.2 находятся в config/rules.json. Полные определения, формулы поддержки и ограничения: docs/METHODOLOGY.md.

Роль	Условия кандидата
coordinator	≥2 seed-предка, ≥3 плательщика, ≥2 получателя, посредничество в верхнем дециле положительных значений
distributor	≥10 разных получателей и ≥10 исходящих переводов
transit	Не seed и не граница, вход и выход есть, отношение выхода к входу 0,8–1,2
consolidator	Не seed и не граница, ≥3 плательщика, отношение выхода к входу ≤0,2
terminal	Не seed и не граница, вход есть, наблюдаемого выхода нет
peripheral	Нет достаточной поддержки более конкретной роли

При пересечении применяется порядок строк таблицы. Карточка сохраняет все совпавшие правила. Имена ролей в CSV соответствуют ТЗ. «Связующий узел» в интерфейсе соответствует coordinator и подчёркивает гипотетичность вывода. Для каждого совпадения показаны поддержка до поправки, коэффициент наблюдаемости и итог. Для seed/границы применяется множитель 0,7.

role_score — эвристическая поддержка правила. priority_score — относительный приоритет проверки: 20% PageRank, 20% посредничество, 20% охват seed, 20% денежный объём max(вход, выход), по 10% входящих и исходящих контрагентов. Все признаки нормируются относительно текущих данных: P=(L+0.5*E)/M, где L — число меньших положительных значений, E — равных, M — размер группы. Одинаковые значения получают 0.5 даже в малом наборе; нулевые признаки — 0. Это разные показатели. Посредничество рассчитывается точно при ≤2 500 активных узлах с внешними контрагентами; выше — по 128 активным исходным вершинам с seed=42. Самопереводы исключены из потоков между контрагентами, метрик ролей, PageRank и временных признаков; исходный оборот и рёбра сохраняют их, карточка показывает отдельно.

Должны ли правила зависеть от размера набора?

Смысл ролей сохраняется: минимумы плательщиков/получателей и отношение потоков не умножаются на N. Пересчитываются относительные ранги, метрики, сообщества и состав очереди проверки. Роли не назначаются по квотам. Изоляты не переключают режим расчёта посредничества и не расходуют случайные опоры; точность остановки PageRank по сумме изменений фиксирована независимо от N.

Дополнительно необычные профили сравниваются только с активными узлами того же колена: x > Q3 + 3*IQR для числа контрагентов и денежного объёма. Нужно ≥20 узлов в группе и IQR>0, иначе система объясняет отказ от оценки. Эти сигналы не меняют роль или приоритет. Формулы и ограничения — METHODOLOGY.md.

Данные и ограничения

Официальный набор: 2 248 узлов, 3 119 рёбер, 4 840 транзакций за июль 2026; исходные 81 seed; только исходящие внутрибанковские переводы ≥5 000 KZT на четыре уровня.

• На depth=4 без выхода дальнейшее движение неизвестно. Такие узлы не объявляются terminal по отсутствию рёбер; ограничение указано в evidence CSV и подробно в интерфейсе.
• Входящие из других источников не видны. Отношение потоков — не полный баланс; выход выше входа не является самостоятельным сигналом нарушения.
• Изоляты сохраняются как отдельные кластеры и получают нулевой структурный приоритет.
• Нет истинных меток ролей: accuracy и калиброванная вероятность не заявляются.
• Сообщества — структурные группы, не установленные преступные организации.
• Даты доступны с точностью до дня; система не утверждает, что конкретный входящий перевод профинансировал конкретный исходящий.
• Приоритет и роли чувствительны к порогам и границам выборки. Формулы — открытая эвристика 2.2, не валидированная банковская модель принятия решений.
• Граф по умолчанию показывает до 350 наиболее приоритетных подходящих узлов, с явным счётчиком. Есть полный обзор и отдельное окружение выбранного узла.
• AI использует ограниченные инструменты: числа и пути вычисляет сервер, объяснение пишет модель. Текст может ошибаться; интерфейс показывает отдельные факты и проверки. Даты доступны для дневных агрегатов конкретных узлов, общий рейтинг за произвольные даты не пересчитывается. Нет доказательств сквозного движения одних и тех же денег или автоматических решений о блокировке.
• Расчёт ограничен 10 000 узлами, 50 000 рёбрами, 100 000 транзакциями; оценка распакованного объёма файла ≤128 МБ. Веб-загрузка дополнительно ограничена 10 МиБ на файл. За раз выполняется один расчёт на процесс.
• gid/src/dst принимаются только как целые в диапазоне signed int64 и передаются в JSON строками. Лишние колонки не используются и не попадают в результат. Суммы — положительные конечные числа; общий оборот каждой таблицы сумм ограничен (2^53−1)/100 KZT, около 90 трлн, для ограничения потери денежной точности. Сверка edges с transactions использует допуск 0,01 KZT без относительного допуска.
• Дата — календарный день: ISO YYYY-MM-DD, Parquet date или timestamp в полночь без часового пояса. Числовые даты, время внутри дня и timezone отклоняются; их нужно явно преобразовать перед загрузкой.
• Загруженные результаты доступны по непредсказуемому run_id. Ссылка является доступом к результату: не делитесь ей вне нужного круга. Это демонстрационный сервис без модели корпоративных пользователей и ролей; реальные банковские данные следует анализировать локально.
• Старые загрузки удаляются только после успешной новой загрузки: старше 24 часов или сверх последних 20. Начальный демонстрационный набор сохраняется.

При перезапуске начальный расчёт переиспользуется только при совпадении режима (синтетика/--data), версии формата результата и полной конфигурации правил; для --data дополнительно сверяются SHA-256 всех трёх файлов. Правила фиксируются при старте процесса. После их изменения нужен перезапуск и новый расчёт; устаревшее состояние не выдаётся за актуальное. Прежние CSV доступны по сохранённым ссылкам выгрузки до истечения срока хранения.

Настройки

Обязательных секретов нет. Пример переменных — .env.example. Переменные передаются через окружение; автоматического чтения .env нет.

Переменная / параметр	По умолчанию	Назначение
PORT / --port	3000	Порт приложения
MONEY_GRAPH_STORAGE	var/runs	Каталог результатов
OPENAI_API_KEY или OPENAI_API_KEY_FILE	Не заданы	Необязательный ключ AI или путь к файлу с ним
OPENAI_MODEL	gpt-5.4-mini-2026-03-17	Модель диалога и выбора проверок
MONEY_GRAPH_ASSISTANT_TOKEN	Не задан	Код доступа к платному AI на публичном сервере
--data у serve	Нет	Предзагрузить набор; без него создаётся синтетический
--rules у analyze	config/rules.json в checkout; встроенные правила в wheel	Альтернативный файл правил

AI-ассистент аналитика

Строка «Спросите о графе» расположена наверху, над показателями и вкладками. Начните с «Кого проверить первым и почему?», затем спросите «Сравни первых двух». Ассистент помнит контекст разговора. «Этот узел» относится к открытой карточке, «эти пятеро» — к явно выбранной группе, «первый в очереди» — к текущей странице с её сортировкой. Общий вопрос не ограничивается открытой карточкой.

Доступны составные фильтры, сравнения, пути, сообщества, объяснение методологии, дневная хронология и структурные сценарии удаления узлов. Ответ содержит реальные ссылки, вычисленные факты и предложения следующих вопросов. Текст — интерпретация AI: его следует сверять с приложенными числами и карточками.

В OpenAI передаются вопрос, контекст экрана, краткая история и запрошенные производные факты графа. Исходные Parquet-файлы целиком и локальные заметки не отправляются. Сервер выполняет до четырёх ограниченных проверок и валидирует ссылки. store: false не заменяет политику обработки данных провайдера. История хранится только в памяти сервера; продолжение доступно 30 минут после последнего ответа. «Новый диалог» сбрасывает контекст. Смена набора или обновление страницы начинает новый разговор.

Ключ остаётся на сервере. Для локального запуска с собственным файлом ключа:

Linux / macOS:

OPENAI_API_KEY_FILE=private/openai_api_key.txt uv run --frozen --no-dev money-graph serve --data ./data/data --port 3010

Windows PowerShell:

$env:OPENAI_API_KEY_FILE = "private/openai_api_key.txt"
uv run --frozen --no-dev money-graph serve --data ./data/data --port 3010

Файл создайте локально, в нём должен быть один API-ключ. Он не входит в репозиторий. Значение переменной окружения OPENAI_API_KEY имеет приоритет над файлом. При отсутствии ключа отключается только ассистент; полный пайплайн, HTML и UI остаются работоспособными. Для публичного сервера задайте отдельный код MONEY_GRAPH_ASSISTANT_TOKEN: пользователь вводит его в интерфейсе, браузер не сохраняет код. Один вопрос одновременно; до 60 вопросов и 180 обращений к модели в час на процесс, до пяти обращений на вопрос. Обработка ограничена 75 секундами, сетевое ожидание одного ответа — 30 секундами. Устройство и примеры.

Production build и деплой

uv sync --frozen --no-dev
npm --prefix web ci
npm --prefix web run build
uv run --frozen --no-dev money-graph serve --host 127.0.0.1 --port 3000

Для VPS используется deploy/money-graph.service. Приложение находится в /opt/money-graph, результаты — /var/lib/money-graph. Служба работает от пользователя moneygraph, с автозапуском и перезапуском при ошибке. Caddy завершает HTTPS и проксирует на loopback. Подробности: deploy/README.md.

Масштабирование за миллион узлов

Текущая веб-версия ограничена 10 000 узлами, 50 000 рёбрами и 100 000 транзакциями. Это проверяемый предел демо; увеличение одного числа не делает NetworkX и общий JSON подходящими для миллиона узлов. В ТЗ требуется описание перехода к этому масштабу, не реализация полного промышленного контура.

План: пакетное чтение Parquet и агрегация на диске → плотные внутренние индексы при сохранении исходных int64 ID → компактные CSR/CSC-графы → фоновые расчёты и версионированные таблицы признаков → выдача ограниченного подграфа интерфейсу. Правила ролей, ограничения наблюдаемости, точность сумм и происхождение каждого признака сохраняются. Приближённые центральности требуют отдельной проверки устойчивости TOP/ролей; нельзя незаметно заменить точную метрику оценкой.

Уже внесённые оптимизации, воспроизводимые замеры, оценки памяти и критерии сохранения качества подробно описаны в SCALING.md. SHA-256 исходников считается потоком без копирования всего файла в память. Полный прогон на миллионе узлов этой версией не заявляется.

Источники

ТЗ кейса, архив организаторов и сопровождающие data/README.md, data/starter/README.md. Базовые определения признаков и схема CSV опираются на предоставленный starter. Внешнее обогащение клиентов не используется. Разработка выполнена с Codex.