HackAlem AI - «Граф денег»

Команда: Those Dudes. GitHub-репозиторий команды.

Локальная исследовательская панель для AML-аналитика: восстанавливает гипотезы о структурных ролях участников транзакционной сети, выделяет кластеры и формирует очередь узлов для проверки. На входе - три файла Parquet, на выходе - интерактивный dashboard и три обязательных CSV.

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

README подготовлен по структуре из «Инструкции для участников HackAlem AI», страницы 1-2. Ниже описана текущая реализация, а не планируемые возможности.

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

• Стартовая форма для загрузки собственных Parquet-файлов; проверка схемы и согласованности таблиц.
• Направленный взвешенный граф: суммы и количество переводов, PageRank, HITS, посредничество, seed-связи и влияние удаления узлов.
• Временные признаки: FIFO-сопоставление в пределах 0/1/2 дней, fan-in/fan-out, повторные маршруты, взаимные переводы и циклы.
• Шесть ролей: consolidator, transit, distributor, terminal, coordinator, peripheral; числовые основания и отдельная оценка уверенности role_score.
• Учёт цензуры depth-4 через p_continue и снижение уверенности в terminal-гипотезе.
• Ансамбль Louvain, стабильность кластеров, отдельный priority_score и сравнение удаления top-N с другими стратегиями.
• Dashboard: сеть с поиском и фильтрами, карточки узлов, транзакции, паттерны, роли, кластеры, методика и локальный помощник.
• Структурированные API-объяснения одного узла или пакета: основания, роль, приоритет, альтернативы, ограничения и следующий шаг проверки; кэш, прогресс, остановка и продолжение.
• Экспорт полных nodes_roles.csv, clusters.csv, top_nodes.csv по отдельности или одним ZIP. Фильтры интерфейса не сокращают выгрузку.

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

1. Запустить проект и открыть локальный интерфейс.
2. Выбрать файлы в полях «Узлы», «Связи», «Переводы» и нажать «Загрузить и открыть анализ». Можно также открыть исходный подготовленный набор.
3. Дождаться проверки и расчёта. Dashboard откроется для конкретного набора: /dashboard?run=<run_id>.
4. В разделе «Роли и приоритет» выбрать узел и сопоставить роль, уверенность, приоритет, числовые признаки и предупреждения.
5. При необходимости отдельно запустить платные объяснения: кнопкой в карточке узла либо в разделе «AI-объяснения для CSV». Для пакета выбрать все узлы или top-список и подтвердить отправку метрик в API.
6. Нажать «Конкурсные 3 CSV» для строгой схемы или «Расширенные CSV / AI» для подробностей. После генерации новых API-объяснений скачать расширенный архив повторно.

Загрузка, локальный анализ, общий чат и экспорт работают без API-ключа. Наличие ключа само по себе не запускает генерацию. Для полного покрытия нужно дождаться объяснений всех выбранных узлов; незавершённые строки явно отмечены.

3. Технологии и AI

Компонент	Реализация
Аналитика	Python, pandas, NumPy, SciPy, PyArrow, NetworkX
HTTP backend	Стандартная библиотека Python, ThreadingHTTPServer; загрузки и фоновые задания
Интерфейс	HTML, CSS, JavaScript, Canvas и SVG; без CDN и отдельной frontend-сборки
Локальный помощник	Детерминированные запросы к рассчитанным данным и read-only инструменты
API-объяснения	OpenAI Agents SDK, Responses API, типизированная схема Pydantic; модель из OPENAI_MODEL, по умолчанию gpt-4.1-mini
Проверки	Python unittest, Node.js test runner, offline evals и dashboard smoke test

Основные зависимости: requirements.txt; дополнительные для API: requirements-ai.txt. Node.js нужен только для JavaScript-тестов. GPU и сервисы NVIDIA текущая реализация не использует.

AI-агент получает метрики, определения признаков, условия допуска ролей и компоненты приоритета. Схема ответа фиксирует назначенную роль и ограничивает ссылки на факты каталогом данного узла. Числовые значения в evidence_json подставляет backend. Модель формулирует интерпретацию, которая требует проверки человеком.

Общий чат dashboard /api/query остаётся локальным. Отдельно доступен CLI-режим sdk с read-only инструментами. Разработка и проверка проекта выполнялись с помощью Codex.

4. Архитектура и методика

Parquet -> проверка -> направленный граф и временные признаки
                     -> роли, кластеры, приоритет, устойчивость
                     -> CSV/JSON -> dashboard и локальный помощник

Метрики + трасса правил -> явный запрос OpenAI -> проверка ответа
                       -> постоянный кэш -> дополненные CSV/ZIP

Роли определяются профильными оценками и условиями допуска с адаптивными порогами. Конкретные gid в правила не зашиваются. role_score учитывает силу профиля, разрыв между кандидатами, устойчивость к возмущению scores и наблюдаемость; это не калиброванная вероятность истинности роли.

p_continue рассчитывается интерпретируемой L2-logistic моделью по входящим признакам, обученной на наблюдаемых depth 1-3. Она помогает учитывать цензуру, но не восстанавливает отсутствующие транзакции.

Реализован medoid ансамбля из 16 Louvain-запусков на симметризованной amount-проекции. Направление сохраняется в остальных расчётах. Infomap, Leiden и SBM рассмотрены в исследовательском отчёте, но не входят в реализованный baseline.

Приоритет отделён от уверенности роли:

priority_score = ECDF(0.30*K + 0.22*E + 0.18*S + 0.15*T + 0.10*X + 0.05*U)

K - структурная связность; E - экспозиция по обороту, числу операций и центральности; S - seed-связи; T - временные и маршрутные признаки; X - выраженность ролевого профиля; U = (1-role_score)*E - ценность проверки неопределённой роли с экспозицией. Итог - относительный ранг, не вероятность нарушения.

Устойчивость сети проверяется удалением N = 0, 1, 5, 10, 20, 50 узлов по priority, betweenness, PageRank и случайному baseline.

src/money_graph/            загрузка, признаки, кластеры, роли, resilience, проверки
run_pipeline.py            пакетный расчёт CSV/JSON
run_project.py             расчёт, подготовка dashboard, запуск сервера
agent_app/datasets.py      загрузка и изоляция пользовательских наборов
agent_app/main.py          HTTP API и CLI
agent_app/structured_explanations.py  структурированный API-агент
agent_app/explanation_jobs.py        пакетные объяснения, кэш и экспорт
dashboard/dist/            готовый интерфейс
input_data/data/           исходные Parquet кейса
output/                    исходные результаты и исследовательский отчёт
runtime/                   пользовательские наборы и кэш API; исключён из Git
tests/, agent_app/tests/    автоматические проверки

Действующие условия, веса, адаптивные пороги и порядок выбора роли: реализованные правила. Scoring и трасса объяснения используют одну функцию из money_graph.rules; формулы и фактические пороги сохраняются в thresholds.json, трассы всех узлов — в decision_traces.json.

Подробнее: архитектура. Исследовательский отчёт описывает рекомендации и альтернативы, не контракт текущей реализации. В частности, transit допускается по FIFO ИЛИ сходству месячных объёмов; только второе условие не подтверждает быстрый транзит.

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

Требуется Python 3.11+; проверенное окружение - Python 3.12. Команды выполняются из корня репозитория. Интернет нужен для установки пакетов, но не для последующего локального анализа.

Windows / PowerShell: новая локальная копия

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run_project.py --open

Откроется http://127.0.0.1:8765/. Команда пересчитывает исходный набор из input_data/data, проверяет результаты, обновляет dashboard и запускает сервер. Остановка - Ctrl+C. Для занятого порта добавьте, например, --port 8766.

Linux / macOS

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python run_project.py --open

Варианты запуска

Ниже python означает Python окружения с установленными зависимостями; в PowerShell можно использовать .\.venv\Scripts\python.exe.

# Расчёт и сборка интерфейса без запуска сервера
python run_project.py --no-server

# Только аналитика; исходный output остаётся без изменений
python run_pipeline.py --data input_data/data --out tmp/check-output --validate

# Открыть готовые результаты без пересчёта
python run_project.py --skip-pipeline --skip-dashboard

# Другой каталог с тремя стандартными именами Parquet
python run_project.py --data "C:\path\to\data" --out "C:\path\to\results" --open

Если исходные данные не входят в вашу копию, запустите сервер с --skip-pipeline --skip-dashboard и передайте файлы через браузер. Готовые файлы dashboard/dist/ должны присутствовать. Открытие index.html как file:// не заменяет backend.

Необязательный OpenAI API

.\.venv\Scripts\python.exe -m pip install -r requirements-ai.txt
if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Откройте .env локально и заполните ключ. Не публикуйте его и не вставляйте в README:

OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1-mini
OPENAI_TIMEOUT_SECONDS=45

После установки дополнительных зависимостей перезапустите сервер. Ключ и модель перечитываются при следующем запросе; переменные окружения имеют приоритет над .env. Модель должна быть доступна вашему API-аккаунту и поддерживать используемую схему ответа.

По умолчанию .gitignore исключает .env и runtime/; для обычной передачи проекта используйте пустой .env.example. Исключение этой закрытой поставки: по явному подтверждению владельца .env с API-ключом включён в Git. Он доступен участникам репозитория и сохраняется в истории; .gitignore не защищает уже отслеживаемый файл. Перед расширением доступа или открытой публикацией отзовите этот ключ и настройте личные ключи вне Git. В приложении ключ используется только backend. Ошибки API показываются явно, без подмены ответа локальным текстом.

В подготовленном рабочем каталоге есть .venv-ai; это локальное окружение, не часть поставки. Его можно использовать вместо .venv, если зависимости уже установлены.

6. Как проверить решение жюри

Сценарий без ключа и платных запросов

1. Выполнить быстрый запуск из раздела 5.
2. Загрузить input_data/data/nodes.parquet, edges.parquet, transactions.parquet.
3. Проверить сводку: 2 248 узлов, 3 119 рёбер, 4 840 транзакций, наблюдаемый оборот около 365,89 млн KZT.
4. В «Роли и приоритет» выбрать первую строку и показать карточку. Объяснить различие между role_score, priority_score и числовыми основаниями.
5. Включить фильтр depth-4 и показать предупреждение: отсутствие наблюдаемого выхода не доказывает конечного получателя.
6. Скачать ZIP. В нём ровно три файла из раздела 8; nodes_roles.csv содержит все 2 248 идентификаторов, top_nodes.csv - 50 строк по убыванию приоритета.

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

python run_pipeline.py --data input_data/data --out tmp/check-output --validate
python -m agent_app.main query "покажи топ 10 кандидатов"

Ожидается status: ok и успешное завершение. Проверки сохраняются в tmp/check-output/validation_report.json, параметры, версии, контрольные суммы и время - в tmp/check-output/run_metadata.json. Во второй команде помощник читает исходный output/, а не временный каталог первой команды.

run_project.py автоматически включает проверку pipeline; флаг --validate относится к run_pipeline.py, а не к run_project.py.

Дополнительный сценарий с API

При наличии разрешённого ключа открыть один узел и нажать «Сгенерировать объяснение роли». Дождаться ответа, скачать CSV заново и проверить explanation_source=openai, заполненные evidence_json, explanation, priority_explanation и неизменность роли и scores. Повторный запрос при тех же данных, модели и версии prompt использует кэш.

Для массового запуска открыть «AI-объяснения для CSV». Запросы платные; есть прогресс, остановка и продолжение. Частичная генерация не считается полным покрытием всех узлов.

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

python -m unittest discover -s tests -v
python -m unittest discover -s agent_app/tests -v
node --test dashboard/network_regression.test.cjs dashboard/upload_regression.test.cjs dashboard/narratives_regression.test.cjs dashboard/assistant_regression.test.cjs
python agent_app/evals/run_local.py
python dashboard/smoke_test.py
python scripts/verify_feedback.py --out output

Для полной проверки SDK установите requirements-ai.txt; иначе SDK-зависимые тесты могут быть пропущены. Реальный ключ тестам не нужен: вызовы модели подменяются. Регрессии включают точную конкурсную схему, временные циклы с поздним стартом, фильтр FIFO, несколько gid, поиск неизвестного узла, границу 200/201 слов и сохранение длинных API-абзацев в расширенном CSV/ZIP. Отдельно предусмотрены 7 offline evals и smoke test сборки dashboard. verify_feedback.py независимо перебирает состояния дат циклов, сверяет каждый узел и проверяет выбор ролей по общей трассе; это не оценка accuracy без меток.

После исправлений по отзыву 23.09.2026 рабочий output/ пересчитан за 14,425 с, с status=ok и успешной валидацией: Python 3.12.14, pandas 2.3.3, NetworkX 3.7, NumPy 2.5.3. Это время pipeline без установки пакетов, сборки интерфейса и API. Проверено 178 тестов плюс 7 offline evals и smoke test. Предыдущие результаты сохранены в runtime/before-feedback-20260923-172819/; прежний контрольный прогон в том же окружении — tmp/readme-verification/. Скорость и численные результаты на другом окружении могут отличаться. Подробности и дельты: отчёт об исправлениях.

7. Данные и внешние интеграции

Файл	Обязательные колонки
nodes.parquet	gid, depth, is_seed
edges.parquet	src, dst, sum_kzt, n_tx, depth
transactions.parquet	src, dst, date, sum_kzt

Исходный набор: 2 248 узлов, 3 119 направленных рёбер, 4 840 переводов за 1-31 июля 2026 года, 365 890 012,01 KZT. В нём 81 seed, 19 изолированных узлов и 444 узла на границе depth-4. Меток истинных ролей и клиентских атрибутов нет.

Идентификаторы должны сохраняться как точные int64/строки; в CSV/API/браузере их нельзя переводить во float или JavaScript Number. Требуются depth=0..4, корректные даты и согласованность edges с агрегатом transactions. Точные повторы переводов сохраняются: без идентификатора операции нельзя считать их ошибочными дублями.

Новые веб-наборы сохраняются в runtime/datasets/<run_id>/; исходные input_data/data/ и output/ не перезаписываются. Подробнее: формат загрузки и API.

Внешний сервис для объяснений - OpenAI API. Структурированный node-explainer отправляет метрики и правила без gid, контрагентов и отдельных транзакций; внешнего поиска нет. SDK tracing отключён, Responses использует store=False, но это не обещание отсутствия всех служебных журналов провайдера. Минимизация передаваемых данных не отменяет необходимости разрешения на их обработку.

Эти ограничения передачи относятся именно к node-explainer. Отдельный CLI-режим query --mode sdk использует read-only инструменты и может включать результаты этих инструментов в контекст модели; не запускайте его на чувствительных данных без отдельной оценки допустимости передачи.

8. Выходные файлы и evidence

Обязательный файл	Обязательные колонки
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

nodes_roles.csv покрывает все входные узлы; scores лежат в 0..1, обязательное evidence содержит числа и не превышает 200 символов. Top-список отсортирован по убыванию приоритета: по умолчанию до 50 узлов, для исходного конкурсного набора не менее 20. Для тестовой сети меньше 20 узлов выгружаются все доступные узлы.

Pipeline сохраняет в output/ или выбранном --out конкурсные nodes_roles.csv, clusters.csv, top_nodes.csv с ровно 6/6/5 колонками. Человекочитаемые русские evidence и why доступны без API, до 200 символов; оговорки о глубине сохраняются. Все дополнительные признаки остаются в *_extended.csv и features.csv.

В dashboard кнопка «Конкурсные 3 CSV» скачивает фиксированную схему без API (?mode=contest). Кнопка «Расширенные CSV / AI» сохраняет все признаки и доступные API-абзацы до 200 слов. Это разные форматы: длинные API-поля не предназначены для строгой конкурсной загрузки. Экспорт всегда покрывает весь набор, независимо от экранных фильтров.

API-объяснения попадают в скачиваемые расширенные серверные снимки, а не перезаписывают исходные CSV. В расширенных nodes_roles.csv и top_nodes.csv добавляются:

• explanation, priority_explanation - объяснение роли и отдельное обоснование приоритета;
• evidence_json - числовые факты со ссылками на признаки и интерпретацией;
• alternative_explanation, limitations, analyst_next_step;
• explanation_source, explanation_status, explanation_model, поля ошибок;
• evidence_rule/why_rule - исходные краткие основания, если соответствующие поля были в исходном файле.

Для готовых ответов evidence и why содержат человекочитаемые абзацы на русском через OpenAI API: факты, причины роли или приоритета и ограничения. Новый лимит — 200 слов на каждое поле, включая числа и оговорки; текст не обрезается. Это отличается от исходного конкурсного ограничения 200 символов: прежние краткие основания сохранены в evidence_rule / why_rule и CSV pipeline. После обновления старые короткие API-ответы нужно сгенерировать заново. Неготовые строки сохраняют исходные основания и получают not_generated или error; длинные API-поля у них пусты. clusters.csv не изменяется. Полный контракт: API-объяснения и экспорт.

Дополнительно pipeline создаёт features.csv, resilience.csv, thresholds.json, validation_report.json, run_metadata.json. Последние два файла позволяют проверить результаты, версии, контрольные суммы входов и время конкретного запуска.

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

• Выборка собрана четырёхшаговым исходящим обходом. Отсутствуют переводы ниже 5 000 KZT и ненаблюдаемые внешние потоки; входы seed неполны. Для другой схемы сбора методику нужно адаптировать.
• Depth-4 правоцензурирован. p_continue - оценка, не доказательство существования или отсутствия дальнейших переводов.
• Дневные даты не задают внутридневной порядок. FIFO, синхронность и циклы не доказывают движение одних и тех же денег или общий контроль.
• Ground truth отсутствует. Синтетические мотивы и тесты проверяют механику, не реальную точность ролей. Проверка ссылок на факты не гарантирует истинность текста LLM.
• Кластеризация использует ненаправленную проекцию и чувствительна к весам: в контрольном прогоне median ARI ансамбля около 0,918, amount-vs-count ARI около 0,425. Leiden, Infomap, SBM и инфраструктура для миллионных графов не реализованы.
• Веб-лимиты: 20 МиБ на файл, 60 МиБ на набор, 128 МиБ объявленного распакованного объёма; 10 000 узлов, 30 000 рёбер, 100 000 транзакций. Один анализ одновременно, тайм-аут 300 секунд. Это пределы входа и ожидания, не гарантия скорости для любого графа.
• Массовые API-объяснения - отдельный платный этап, не входят в пятиминутный локальный расчёт. Одновременно выполняются до трёх запросов; возможны ошибки сервиса и отклонённые ответы. Успешные результаты сохраняются для продолжения.
• Нет многопользовательской аутентификации. Сервер не предназначен для публикации в интернет. Наборы и кэш сохраняются на локальном диске без автоматической очистки; хранение и права доступа контролирует владелец компьютера.
• Зависимости заданы диапазонами, а не полным lock-файлом. Фиксированные random seeds не гарантируют побитово одинаковый результат при смене библиотек или платформы.

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

Публичная deployed-ссылка в проекте не указана. Текущая версия запускается локально:

• Стартовая страница.
• Dashboard исходного набора, если он подготовлен.

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

11. Командные роли и подготовка к сдаче

Масштабирование до 1 млн узлов — план, не реализованная возможность

Текущий MVP рассчитан на небольшие локальные наборы: NetworkX, pandas и браузер хранят значимую часть данных в памяти. Пятиминутный результат на исходном наборе не распространяется на миллион узлов.

• Агрегации по узлу/ребру/дню перенести в DuckDB или потоковый Polars поверх разбитого Parquet; не загружать все транзакции одновременно.
• Использовать компактные числовые индексы и CSR/CSC в графовой библиотеке (например, igraph/NetworKit). Таблицу точных int64 gid держать отдельно; оценивать память по числу рёбер, не только узлов. Избегать Python-объектов на каждое ребро.
• Betweenness считать приближённо по фиксированной выборке источников с оценкой ошибки; ограничивать длину/число маршрутов и циклов, предварительно выделять сильносвязные компоненты. Тайм-аут или усечение отражать в metadata, не выдавать неполный счёт за точный.
• Считать кластеры по компонентам, временные мотивы по разделам и окнам дат с перекрытием ≥7 дней; исключать повторный счёт на границах. Исследовать устойчивость к удалению транзакций и сдвигам дат/сумм отдельно от текущего шума профилей.
• Выдавать в браузер агрегаты и выбранный подграф с серверной пагинацией; API-объяснения генерировать по запросу/очереди с лимитом бюджета. Хранить признаки и версии расчёта отдельно от объяснений.
• До заявления производительности измерить peak RAM, время и погрешность на ступенях 10 тыс. → 100 тыс. → 1 млн узлов. Held-out проверка p_continue по глубинам/периодам остаётся исследовательской задачей.

Ответственность и сдача

Роль в команде из трёх человек	Зона ответственности
PM + Frontend	Объём MVP, интерфейс загрузки и исследования сети, экспорт, демо и описание решения
Backend	Валидация Parquet, признаки, роли, кластеры, priority, resilience и контракт CSV
Agentic AI	Структурированные объяснения через API, привязка к фактам, безопасная конфигурация, кэш и проверки

Перед сдачей по инструкции организаторов:

• Проверить основной сценарий «Parquet -> dashboard -> три CSV».
• Проверить состав публикуемых файлов: не отправлять .env, ключи, локальные окружения, пользовательские наборы и API-кэш. .gitignore не удаляет секреты, уже попавшие в историю Git.
• Убедиться, что публикация исходных данных разрешена условиями кейса; передавать только разрешённые файлы.
• Отправить последнюю версию кода и README в выданный платформой GitHub-репозиторий команды.
• На странице выбранного кейса нажать «Сдать решение» и заполнить название и описание; обновления возможны до дедлайна платформы.
• Добавить публичную demo-ссылку только если такая версия действительно развёрнута.

Персональные контакты при необходимости заполняют участники. Публикация кода в GitHub не означает сдачу решения на платформе: этот шаг команда выполняет отдельно.