Граф денег

AML-инструмент аналитика: по 4-хоповому графу переводов определяет, кого из 2 248 клиентов проверять первым и почему. HackAlem AI, трек 2 «Граф денег».

Экспертам и жюри: установка, запуск и проверка основного сценария — без API-ключа, без базы данных и без Docker. Достаточно Node.js и двух команд.

Содержание

• Что это
• Быстрый старт
• Продакшен-запуск и деплой
• Переменные окружения
• Как проверить основной сценарий
• Выгрузки
• Метод
• Архитектура
• Инструменты ассистента
• Ограничения
• Масштабирование до ~1 млн узлов
• Тесты и проверки
• Команды
• Команда
• Сторонние компоненты и предварительные наработки

Что это

«Граф денег» — рабочее место AML-аналитика. На входе — граф исходящих внутрибанковских переводов от 81 известного клиента (seed) на глубину 4 колена: 2 248 узлов, 3 119 рёбер, 4 840 транзакций, июль 2026, переводы от 5 000 KZT.

Пайплайн считает метрики каждого узла и присваивает ему роль (ровно одну из шести по ТЗ), кластер и приоритет проверки, а у каждой строки есть evidence — объяснение с числами. Экран показывает сеть с направлением денег и ролями, ищет любой gid и открывает карточку узла. AI-ассистент отвечает на вопросы вида «кого проверять первым и почему?», вызывая инструменты только для чтения над тем же анализом.

Выводы — это гипотезы для проверки, а не обвинения. Разметки «виновен / не виновен» в данных нет, поэтому каждая роль — формальное правило с порогом, которое любой может проверить руками. Тексты для пользователя (интерфейс, evidence, why, hypothesis, ответы ассистента) — на русском, код — на английском.

Быстрый старт

Нужно: Node.js ≥ 22 и pnpm 10. Python, база данных и Docker не нужны.

Если их нет:

1. Node.js — установщик LTS-версии с https://nodejs.org (Windows, macOS, Linux; npm входит в комплект). Или менеджером пакетов: winget install OpenJS.NodeJS.LTS (Windows), brew install node (macOS).
2. pnpm — одной командой в новом окне терминала: npm install -g pnpm@10.
3. Проверка: node -v печатает v22… или новее, pnpm -v — 10….

Без глобальной установки pnpm можно вызывать через npx pnpm@10 вместо pnpm в командах ниже.

pnpm install
cp .env.example .env          # PowerShell: Copy-Item .env.example .env
pnpm pipeline                 # data/*.parquet → output/*.csv + output/analysis.json, секунды
pnpm dev                      # http://localhost:3000

• pnpm pipeline читает сырые data/*.parquet (лежат в репозитории, 87 КБ) и пишет output/nodes_roles.csv, output/clusters.csv, output/top_nodes.csv, output/analysis.json и output/run_summary.json. Работает ~3–6 секунд (по ТЗ допустимо до 5 минут), печатает время, число строк и заявленные особенности данных и падает с ошибкой, если в nodes_roles.csv не 2 248 строк или в top_nodes.csv меньше 20.
• pnpm dev и pnpm build сами запускают пайплайн (predev / prebuild), так что pnpm install && pnpm dev — достаточно. Отдельный pnpm pipeline нужен, чтобы посмотреть выгрузки без запуска сервера.
• CSV — UTF-8 без BOM: так их читает pandas.read_csv без параметров, а первая колонка называется ровно gid. В Excel открывать через «Данные → Из текста/CSV → UTF-8», иначе кириллица в evidence отобразится кракозябрами.
• База данных и Docker не нужны. .env.example уже содержит LLM_PROVIDER=mock — ассистент работает без ключа и без сети.

Продакшен-запуск и деплой

На любой машине или сервере с Node.js ≥ 22 и pnpm 10 (установка — в разделе выше):

pnpm install --frozen-lockfile
cp .env.example .env          # для живой модели: LLM_PROVIDER=responses и LLM_API_KEY
pnpm build                    # сам запускает пайплайн, затем собирает Next.js
pnpm start                    # http://localhost:3000; порт меняется переменной PORT

Приложение — один Node-процесс, без базы и внешних сервисов. Переменные задаются в .env или в окружении хостинга.

Переменные окружения

.env.example полный и содержит LLM_PROVIDER=mock, так что его копия сразу даёт рабочий продукт.

Переменная	Для проверки	Для живой модели	Смысл
LLM_PROVIDER	mock	responses	mock, responses (OpenAI Responses API) или chat
LLM_MODEL	не используется	gpt-6-luna	Идентификатор модели
LLM_API_KEY	пусто	ключ OpenAI API	Настоящий ключ никогда не коммитится
LLM_BASE_URL	пусто	пусто	Только для OpenAI-совместимого эндпоинта с chat

LLM_PROVIDER=mock — способ проверить основной сценарий без ключа: сценарный агент вызывает настоящие инструменты через тот же диспетчер, что и живая модель, без ключа и без сети. Это продукт без модели, а не заглушка: инструмент, который должен отказать, отказывает и здесь.

Остальные переменные в .env.example (встроенные инструменты OpenAI) унаследованы от шаблона и продуктом не используются.

Как проверить основной сценарий

1. Запустить пайплайн: pnpm pipeline. В консоли — время выполнения и счётчики строк.

2. Проверить выгрузки:

   • в output/nodes_roles.csv ровно 2 248 строк данных плюс заголовок, шесть обязательных колонок (gid, role, role_score, cluster_id, priority_score, evidence) заполнены в каждой строке;
   • в output/top_nodes.csv — не менее 20 строк, по убыванию приоритета;
   • в output/clusters.csv — строка на кластер, у каждого гипотеза.

   Подсчёт строк на любой ОС (печатает 2248):

   node -e "console.log(require('fs').readFileSync('output/nodes_roles.csv','utf8').trim().split('\n').length - 1)"
   

3. Открыть экран: pnpm dev, затем http://localhost:3000 (по умолчанию тёмная тема, переключатель вверху справа). Сеть раскрашена по ролям (можно переключить на раскраску по кластерам), стрелки показывают направление денег, размер — приоритет. Чипы ролей над графом называют каждый цвет и включают/выключают роль; периферия (80% узлов) скрыта по умолчанию — чип «Периферийный» включает её. Справа открыта вкладка «Топ» — список приоритетов.

4. Найти gid: вставить любой gid из nodes_roles.csv в поиск. Узел фокусируется, соседи подсвечиваются (даже скрытые периферийные), открывается карточка: роль и сила правила, evidence, метрики, флаги аномалий, крупнейшие отправители и получатели.

5. Показать путь денег: кнопка «Показать путь денег» в карточке прослеживает самые крупные входящие рёбра назад до seed и по коленам подсвечивает маршрут на графе, внизу — итог в виде гипотезы («деньги могли дойти за N колен от K seed»). Вкладка «Кластеры»: клик по кластеру подсвечивает его на графе.

6. Спросить ассистента «кого проверять первым и почему?», затем «кто собирает деньги с этих пятерых?» и, по желанию, «что если убрать первых пятерых?». В панели активности видно каждый вызов инструмента — имя, аргументы, результат и время, — а ответ собран из этих результатов. Любой gid в ответе кликабелен.

Выгрузки

Все три CSV строго следуют схеме ТЗ: обязательные колонки идут первыми в порядке ТЗ, дополнительные — после них.

output/nodes_roles.csv — строка на каждый узел, 2 248 строк.

Колонка	Смысл
gid	Идентификатор клиента, хранится строкой (значения ~1e17 больше безопасного целого JS)
role	Одна из consolidator, transit, distributor, terminal, coordinator, peripheral
role_score	0–1: насколько узел превышает порог своей роли
cluster_id	Сообщество Louvain
priority_score	0–1: приоритет проверки
evidence	На русском, ≤ 200 символов, с числами
далее	дополнительные колонки: метрики ниже (колено, seed, степени, суммы, коэффициент пропуска, PageRank, HITS, посредничество, seed выше по потоку, быстрый транзит, обрыв) и flags

output/clusters.csv — строка на кластер: cluster_id, n_nodes, n_seed, sum_kzt_internal, top_gids, hypothesis. sum_kzt_internal — сумма рёбер, оба конца которых внутри кластера; hypothesis — на русском, сформулирована как предмет проверки.

output/top_nodes.csv — 50 строк (ТЗ требует не менее 20): rank, gid, role, priority_score, why. why называет два-три слагаемых, которые сильнее всего дали вклад в приоритет, с их значениями.

Во всех CSV gid — просто цифры, булевы значения — true/false, отсутствующее значение (например, pass_through у узла, который ничего не получил) — пустая ячейка, списки (top_gids, flags) соединены через |.

output/run_summary.json — журнал одного запуска: SHA-256 каждого входного файла, число строк, число узлов по ролям, время каждого этапа и заявленные особенности данных как предупреждения (изолированные seed, узлы, которые отдают больше, чем по данным получили, узлы 4-го колена без исходящих).

output/analysis.json — всё, что читают экран и ассистент: статистика, пороги ролей (thresholds), каждый узел с метриками, вердиктом и заранее посчитанной раскладкой, каждое ребро с датами первой и последней транзакции, кластеры и топ-лист. Его форма — zod-схема в src/server/graph/model/graph.schema.ts.

Метод

Метрики

Считаются на направленном взвешенном графе для каждого узла:

Метрика	Определение
in_deg, out_deg	Число различных отправителей / получателей
in_kzt, out_kzt	KZT получено / отправлено внутри графа
in_tx, out_tx	Число переводов — суммы и количества дают разные сигналы
pass_through	out_kzt / in_kzt, пусто, если ничего не пришло. Не используется для seed
pagerank	PageRank со взвешиванием по sum_kzt, α = 0.85, «висячая» масса распределяется равномерно
hub, authority	HITS: хабы шлют хорошим сборщикам, авторитеты собирают от хороших хабов
betweenness	Посредничество по Брандесу, направленное, нормировано на (n−1)(n−2)
seeds_upstream	Сколько различных seed достигают узла по направленным рёбрам
fast_transit_share	Доля исходящих KZT, отправленных в течение 2 дней после входящего перевода (по датам)
truncated	4-е колено и нет исходящих рёбер: остановился обход, а не деньги

Наши PageRank, HITS и betweenness сверены с networkx на всех 2 248 узлах и совпадают с точностью до 1e-14.

Роли

Каждая роль — формальное правило. Правила применяются в этом порядке, выигрывает первое совпавшее. role_score — насколько узел превысил порог: для значения v и порога t это (v − t) / (v + t), так что узел ровно на пороге получает 0, а далеко за ним — почти 1.

#	Роль / случай	Правило	Пороги (ROLE_THRESHOLDS)	Узлов
1	truncated (флаг)	4-е колено и out_deg = 0: остановился обход, а не деньги. Никогда не terminal; consolidator — только если входы проходят правило 4, иначе peripheral	колено ≥ 4; role_score ≤ 0.5	444 с флагом
2	coordinator	Начало цепочки с ветвлением в слой сбора/распределения: seed или узел колена ≤ 1, который шлёт нескольким получателям и через который за 2 шага достигается много консолидаторов/распределителей по нескольким отдельным веткам	колено ≤ 1; out_deg ≥ 3; ≥ 15 таких узлов в пределах 2 шагов; ≥ 3 прямые ветки	16
3	distributor	Веер: много получателей, мало отправителей	out_deg ≥ 10 и out_deg ≥ 2.5 × in_deg	53
4	consolidator	Собирает от многих и мало отдаёт дальше	(in_deg ≥ 5, или in_deg ≥ 3 при ≥ 2 seed выше по потоку) и pass_through < 0.5	94
5	transit	Пришло ≈ ушло, небольшие степени; пересылка в течение 2 дней повышает скор. Никогда для seed (его приход занижен)	0.8 ≤ pass_through ≤ 1.2; in_deg, out_deg ≤ 8; флаг fast_transit при ≥ 50% пересланного за 2 дня	68
6	terminal	Деньги приходят и остаются — и не потому, что обход остановился	out_deg = 0, колено < 4 и (in_deg ≥ 2 или in_kzt ≥ 200 000 ₸)	219
7	peripheral	Всё остальное; evidence говорит, какой порог не пройден	—	1 798

Применённые числа выгружаются при каждом запуске как thresholds в output/analysis.json; если эта таблица и файл расходятся, верен файл.

Для масштаба, на этих данных: у 51 узла in_deg ≥ 5; у 64 — out_deg ≥ 10; у 70 узлов, не seed, pass_through от 0.8 до 1.2; 444 узла с обрывом; у 1 091 нет исходящих при колене < 4, из них 219 проходят порог terminal. Число узлов по ролям для каждого запуска — в output/run_summary.json.

Флаги аномалий

Флаги стоят рядом с ролью и никогда не меняют ни её, ни скор, ни приоритет. Они видны бейджами в карточке узла и в колонке flags в nodes_roles.csv (src/server/graph/model/anomalies.ts, пороги также выгружаются в analysis.json):

Флаг	Правило	Узлов
split (дробление сумм)	один отправитель сделал ≥ 3 перевода узлу в один день, все в пределах ±10% от медианы	6
sync_inflow (синхронный приход)	в какой-то день узел получил от ≥ 3 различных плательщиков	38
cycle (возвратный поток)	узел лежит на направленном цикле длиной ≤ 6 — деньги возвращаются	303
repeat_route (повторяющийся маршрут)	средний узел B цепочки A→B→C с ≥ 2 переводами по обоим звеньям, и в ≥ 2 датах B переслал C в течение 2 дней после получения от A	54
burst (всплеск активности)	в какой-то день у узла ≥ 3 транзакций и ≥ 3× его среднего дневного числа (нужно ≥ 2 активных дня)	10
depth_outlier (аномальный профиль для колена)	оборот log1p(in+out) не ниже 95-го перцентиля узлов того же колена (слои ≥ 20 узлов)	120
fast_transit (быстрый транзит)	≥ 50% исходящих KZT ушли в течение 2 дней после входящего перевода	275
truncated (обрыв обхода)	4-е колено без исходящих переводов (см. «Роли»)	444

Дробление ниже порога выгрузки 5 000 KZT в этих данных невидимо, поэтому split может только недосчитывать.

Кластеры

Выделение сообществ Louvain (graphology-communities-louvain) на ненаправленной проекции, отдельно в каждой слабосвязной компоненте; встречные рёбра объединяются, вес — log1p(sum_kzt) + 0.25 · log1p(n_tx). Направление отбрасывается только для кластеризации — все метрики и роли выше считаются на направленном графе. Генератор случайных чисел зафиксирован (42), а номера кластеров упорядочены по внутреннему обороту, так что на тех же данных кластеры одинаковы при каждом запуске. Каждый кластер получает гипотезу на русском по составу ролей и числу seed. На этих данных: 84 кластера (изолированные seed — кластеры из одного узла).

Приоритет

priority_score отвечает на вопрос «что проверять следующим», а не «кто виновен». Это взвешенная сумма слагаемых, каждое нормировано к 0–1 (src/server/graph/model/priority.ts):

Слагаемое	Вес	Нормировка
Сила роли	0.25	вес роли × role_score (coordinator 1.0, consolidator 0.95, distributor 0.9, transit 0.8, terminal 0.55, peripheral 0)
Объём потока	0.20	log1p(in_kzt + out_kzt) ÷ максимум
Охват seed	0.15	seeds_upstream ÷ максимум
Посредничество	0.15	÷ максимум
PageRank	0.15	÷ максимум
Плотность seed в кластере	0.10	seed ÷ узлов в кластере узла

Затем × 0.75 для seed (аналитику он уже известен) и × 0.85 для узла с обрывом (исходящее поведение не наблюдается). why называет два-три слагаемых с наибольшим вкладом и их значения, плюс штраф, если он есть. Ни один seed не попадает в топ-50.

Как учтены ловушки данных

• Обрыв на 4-м колене. 444 узла стоят на 4-м колене без исходящих рёбер, потому что обход закончился. Они никогда не terminal: у них флаг truncated, role_score ограничен 0.5, приоритет снижен, а evidence говорит «обход остановлен на 4-м колене».
• Приход seed занижен. Граф собран от seed по исходящим переводам, поэтому деньги, полученные seed извне выборки, отсутствуют, и pass_through 20+ — артефакт выгрузки. pass_through никогда не используется для роли seed.
• Суммы и количества различаются. Один перевод на 4 млн и сорок по 100 тыс. дают одинаковый in_kzt; степени, число переводов и суммы сохраняются и показываются все.
• Порог 5 000 KZT. Меньших переводов нет, поэтому степень узла — оценка снизу, а «маленький» поток может быть раздробленным.
• Фрагменты. В графе 35 слабосвязных компонент: 16 компонент плюс 19 изолированных seed. Изолированные seed сохраняются, получают роль, как любой узел, и отмечаются как белое пятно.
• Нет разметки. Меток нет, поэтому ничего не обучается. Объяснимые правила с порогами позволяют аналитику — и жюри — проверить любой вердикт по числам самого узла за минуту.

Архитектура

Одно приложение Next.js, TypeScript от начала до конца: пайплайн, который пишет CSV, и сервер, который отвечает ассистенту, вызывают одни и те же функции.

data/*.parquet
   │  scripts/pipeline.ts            CLI: --data ./data --out ./output; время и число строк
   ▼
src/server/graph/repo/               только файловый ввод-вывод
   parquet.ts                        readRawGraph: hyparquet + ZSTD; gid → строка, date → 'YYYY-MM-DD'
   outputs.ts                        writeOutputs: 3 CSV + analysis.json
   analysis.ts                       readAnalysis: синхронно, с кэшем, валидация zod-схемой
   ▼
src/server/graph/model/              чистый алгоритм: синхронный, без ввода-вывода, покрыт тестами
   graph.schema.ts                   контракт (zod): все структуры ниже
   metrics.ts                        степени, суммы, коэффициент пропуска, PageRank, HITS, посредничество…
   roles.ts                          ROLE_THRESHOLDS, assignRoles
   anomalies.ts                      флаги аномалий
   clusters.ts                       Louvain, сводки кластеров и гипотезы
   priority.ts                       scorePriority, rankTop
   queries.ts                        карточка узла, сборщики, трассировка потока, изъятие, белые пятна
   ▼
src/server/graph/usecase/
   analyze.ts                        метрики → роли → кластеры → раскладка → приоритет → топ
   layout.ts                         ForceAtlas2 с фиксированным зерном: картинка не «прыгает»
   getAnalysis.ts                    единственная точка входа страницы
   tools.ts                          семь инструментов ассистента
   ▼
src/app/ + src/views/graph           экран сети на Sigma.js (WebGL), карточка, топ, кластеры
src/widgets/assistant                чат рядом с графом, панель активности
src/server/agent/usecase             цикл агента, реестр инструментов, промпт, mock-адаптер
app/api/chat/route.ts                POST /api/chat — единственный сетевой вызов интерфейса

Страница читает output/analysis.json и никогда не разбирает parquet во время запроса, поэтому обработчики инструментов синхронные, а экран открывается мгновенно.

Почему TypeScript, а не Python. Одна среда выполнения — одна установка для экспертов, а проект, который эксперты не смогли запустить, выбывает. Инструменты ассистента вызывают ровно те функции, которые построили CSV, поэтому чат и файлы не могут разойтись. Прежде чем выбрать этот путь, мы сверили графовые алгоритмы с networkx (1e-14); весь расчёт занимает около трети секунды. Python- стартер организаторов использован только как справка.

Структура кода. Интерфейс — Feature-Sliced Design (app → views → widgets → features → entities → shared, импорты только вниз). Сервер — src/server/ по уровням (kernel → <domain>/model → <domain>/repo → <domain>/usecase), тоже только вниз. Оба правила проверяет eslint-plugin-boundaries, нарушение ломает сборку. docs/architecture.md — спецификация; docs/plan.md и docs/decisions.md — как распределялась работа и почему.

Стек

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · Radix UI · Zod · hyparquet · graphology (Louvain, ForceAtlas2) · Sigma.js 3 с @react-sigma/core · OpenAI SDK (Responses API) · Vitest · ESLint.

LLM-провайдеры

LLM_PROVIDER выбирает, как ассистент общается с моделью. Инструменты и цикл одинаковы во всех трёх вариантах; меняется только протокол.

Значение	Протокол	Для чего
responses	OpenAI Responses API	Живая модель gpt-6-luna
chat	Chat Completions	Любой OpenAI-совместимый эндпоинт (задать LLM_BASE_URL)
mock	—	Без ключа и без сети. Проверка и офлайн-демо

Инструменты ассистента

Все инструменты только читают, поэтому подтверждения не требуют. Каждый проверяет аргументы через zod (аргументы — свободный текст модели), перепроверяет, что каждый gid существует, и иначе возвращает отказ. Диспетчер никогда не бросает исключение: упавший инструмент — это строка «ошибка».

Инструмент	Аргументы	Возвращает
get_top_nodes	limit? (1–50), role?, clusterId?	Строки топа по приоритету с why
get_node	gid	Карточку узла: метрики, роль, evidence, топ-5 входящих и исходящих
get_cluster	clusterId	Строку кластера и его главных участников
find_collectors	gids (2–20), maxHops? (1–4)	Узлы, до которых доходят деньги ≥ 2 из gid, с полученными KZT
trace_flow	gid, direction, maxHops?	Подграф рёбер ниже или выше по потоку от gid
simulate_removal	gids	Компоненты и охват seed до и после изъятия gid
coverage_gaps	—	Каких данных не хватает и какой запрос сделать в банк следующим

Промпт требует, чтобы каждое число в ответе бралось из результата инструмента, каждое утверждение ссылалось на gid, выводы формулировались как гипотезы, а ассистент говорил, чего данные показать не могут (обрыв, приход seed).

Ограничения

• Выборка односторонняя и обрезанная. Только исходящие переводы от seed, четыре колена, один месяц. Приход в seed и всё дальше 4-го колена не видно; узел с обрывом нельзя считать конечным получателем.
• Переводов меньше 5 000 KZT нет, поэтому дробление на мелкие суммы не видно.
• Только внутрибанковские переводы. Наличные, другие банки и выход в крипту выглядят как конечные получатели или отсутствуют.
• Правила, а не модель. Пороги откалиброваны на одном этом датасете и на другом потребуют перенастройки; без разметки точность и полноту измерить нельзя.
• Роли взаимоисключающие. Узел, который и собирает, и распределяет, получает первую совпавшую роль; остальное видно по метрикам в его строке.
• Louvain в общем случае недетерминирован; фиксированное зерно делает результат воспроизводимым, но не единственным. Ненаправленная кластеризация не учитывает, куда текут деньги внутри кластера.
• Ассистент прав ровно настолько, насколько правы его инструменты; он объясняет правила и не добавляет знаний сверх данных.

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

Сейчас всё считается в памяти за треть секунды на 2 248 узлах. При миллионе узлов и десятках миллионов переводов изменится следующее:

• Чтение. Читать parquet потоково по группам строк и колонкам, а не целиком; строить смежность сразу в сжатые разреженные массивы (CSR), а не в JS-объекты.
• Метрики. PageRank и HITS — итерации разреженного умножения матрицы на вектор (линейно по рёбрам за итерацию). Точное посредничество по Брандесу — O(V·E) и становится неподъёмным, поэтому — приближённое посредничество по выборке из k опорных вершин. Тяжёлые расчёты — в графовый движок: igraph или graph-tool на одной машине, GraphFrames/Spark или графовая БД для масштаба банка.
• Кластеризация. Leiden вместо Louvain: быстрее на больших графах и гарантирует связные сообщества.
• Инкрементальный пересчёт. Новые транзакции приходят ежедневно; пересчитывать только затронутые окрестности и роли, а полный пересчёт оставить ночным заданием.
• Интерфейс. Sigma.js тянет порядка 100 тыс. узлов в браузере. Дальше экран показывает сводки кластеров и эго-сети вокруг найденного gid с фильтрацией на сервере, заранее посчитанными тайлами и уровнями детализации вместо всего графа.
• Инструменты ассистента. Запросы — через индекс или графовую БД (окрестность, k шагов, топ по приоритету) вместо перебора массивов в памяти; контракты инструментов не меняются.

Тесты и проверки

pnpm check

Одна команда: проверка типов, линтер с --max-warnings 0 и юнит-тесты, параллельно. Предупреждения считаются ошибками. Ничего не нужно запускать заранее — ни базы, ни API-ключа, ни сети. Алгоритм в src/server/graph/model покрыт юнит-тестами на небольших графах, собранных вручную: по тесту на каждую роль и флаг, плюс ловушки обрыва и seed.

Структурные проверки шаблона тоже действуют: src/app/globals.spec.ts (стили собираются и следуют правилам токенов), src/shared/ui/rawControls.spec.ts (нет «сырых» элементов форм на экранах) и src/server/agent/usecase/tools.spec.ts (диспетчер инструментов никогда не бросает исключение).

Команды

Команда	Что делает
pnpm pipeline	data/*.parquet → output/*.csv + output/analysis.json
pnpm dev	Dev-сервер Next на http://localhost:3000
pnpm build / pnpm start	Продакшен-сборка и запуск
pnpm check	Типы, линтер и юнит-тесты параллельно
pnpm test	Только юнит-тесты
pnpm verify	Типы и линтер
pnpm format	Prettier

База данных продуктом не используется: необязательный слой PostgreSQL/Prisma из шаблона удалён.

Команда

Участник	Зона ответственности
Ораз Исабеков	Контракт данных, интерфейс, README
Бекжан	Пайплайн, инструменты ассистента, промпт
Саян Кареев	Алгоритм: метрики, роли, кластеры, приоритет, запросы

Сторонние компоненты и предварительные наработки

Обязательное раскрытие (§5.4.4).

Заранее подготовленный шаблон. Проект начат с универсального стартового шаблона, подготовленного до соревнования и закоммиченного как 8d67410 chore: pre-existing hackathon starter template: оболочка приложения Next.js, провайдер-независимый цикл LLM-агента с реестром инструментов и инструментом часов без предметной логики, чат-интерфейс с панелью активности, библиотека UI-компонентов, система дизайн-токенов и архитектура, проверяемая линтером. Функциональности по этой задаче в нём не было. Всё, что решает задачу, — контракт данных, пайплайн, метрики, правила ролей, кластеризация и приоритет, флаги аномалий, графовые инструменты, экран сети и этот README — сделано во время соревновательной части и видно в истории коммитов после этого коммита.

Материалы организаторов. Датасет (data/edges.parquet, data/nodes.parquet, data/transactions.parquet, 4-хоповый граф внутрибанковских переводов, июль 2026) и ТЗ предоставлены организаторами для использования в рамках хакатона. Python-стартер организаторов (starter.py) прочитан как справка по схеме выгрузок и ловушкам данных; его код не используется — пайплайн наш, на TypeScript.

Модель. OpenAI gpt-6-luna через OpenAI Responses API (LLM_PROVIDER=responses), проприетарная, используется на условиях OpenAI API. Никакая модель не обучалась и не дообучалась. LLM_PROVIDER=mock модель не использует вовсе.

Зависимости времени выполнения (полный список и версии — в package.json):

Пакет	Для чего	Лицензия
hyparquet, hyparquet-compressors	Чтение parquet со сжатием ZSTD	MIT
graphology	Структура данных графа	MIT
graphology-communities-louvain	Кластеризация Louvain	MIT
graphology-layout-forceatlas2	Заранее посчитанная раскладка	MIT
sigma, @react-sigma/core	WebGL-отрисовка сети	MIT
@sigma/node-border	Ореол узлов (свечение)	MIT
next, react, react-dom	Фреймворк приложения	MIT
radix-ui, @heroicons/react, clsx	UI-примитивы, иконки, классы	MIT
tailwindcss (dev)	Стили	MIT
zod	Схемы и валидация	MIT
openai	Клиент OpenAI API	Apache-2.0
dotenv	Загрузка .env	BSD-2-Clause
server-only	Защита границы сервер/клиент	MIT

Инструменты разработки — TypeScript, ESLint и его плагины, Prettier, Vitest, tsx — каждый под своей лицензией, перечислены в package.json.

Графовые алгоритмы не из библиотек — PageRank, HITS, посредничество по Брандесу, seeds_upstream, быстрый транзит, правила ролей и приоритет — наш код в src/server/graph/model, сверенный с networkx.