Freedom Graph — Ascend

Объяснимая аналитика финансовых связей для AML-аналитика банка. Проект команды Ascend для HackAlem AI: от транзакционного графа к приоритетам проверки, наблюдаемым основаниям и досье аналитика.

Жюри: инструкция быстрого запуска и проверки. Весь комплект уже в репозитории: три Parquet, готовый расчёт и сборка сайта. После скачивания и распаковки репозитория выполните py -3.12 jury_start.py в Windows или python3 jury_start.py в Linux/macOS и откройте http://127.0.0.1:8000/. Ключи OpenAI и Telegram для этого не нужны. GitHub хранит код; постоянный публичный сайт пока не развёрнут.

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

1. Какую проблему решает проект

В сети переводов аналитику нужно определить, какие узлы проверить первыми, кто собирает или распределяет средства и какие связи подтверждают рабочую гипотезу. Freedom Graph рассчитывает признаки графа, назначает объяснимые роли и приоритеты, показывает контекст клиента по GID и помогает сформировать проверяемый отчёт.

Основной пользователь — AML-аналитик банка. Интерфейс предназначен для ручного исследования наблюдаемой сети, а не для автоматического принятия санкционных решений.

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

Основной сайт

• React-dashboard с backend API: статистика и период снимка, список приоритетных узлов, точный поиск по GID, фильтры ролей и кластеров.
• Интерактивный направленный граф: масштабирование, перемещение, выбор узлов и рёбер, просмотр соседей, раскраска по приоритету, роли или кластеру. Анимация потоков включается отдельно, по умолчанию выключена.
• Карточка узла: роль, role_score, priority_score, кластер, входящие и исходящие связи, полученные и отправленные суммы, evidence и пояснение правила. Отдельно отмечаются seed, граница обхода и изоляты.
• Выбор уровня приоритета показывает соответствующие узлы с непосредственными соседями и связями внутри окружения. Обычный список расширяется порциями по 100 узлов.
• «Расследование»: агрегаты связей, один кратчайший направленный путь до шести рёбер, проверка совместимости диапазонов дат, досье до 30 фактов и выгрузка PDF- и Markdown-отчётов. PDF формируется сервером по фактам выбранного снимка, а не по тексту клиента.
• Скачивание nodes_roles.csv, clusters.csv, top_nodes.csv из того же опубликованного снимка, который использует API.
• Переключатель RU / KZ / EN для основной оболочки. Часть новых аналитических панелей, сообщений API и объяснений пока остаётся на русском.

Рабочая точка входа: Frontend/src/main.tsx → DesignDashboard.tsx. Старый App.tsx с mock-данными сохранён в исходниках, но не является текущим основным экраном.

Расчёт графа

• Загрузка трёх Parquet-файлов; валидация GID, дат, сумм и связей; сверка агрегированных рёбер с транзакциями.
• Направленный граф, степени узлов, наблюдаемые потоки, betweenness, PageRank, достижимость от seed; Louvain на неориентированной проекции для выделения кластеров.
• Шесть ролей: consolidator, distributor, transit, terminal, coordinator, peripheral. Правила, пороги и веса — в methodology.yaml.
• Детерминированные объяснения, рейтинг и гипотезы кластеров. role_score — эвристическое соответствие правилу; priority_score — относительная очерёдность проверки.
• Дополнительные анализы: временные паттерны, цепочки и циклы, признаки дробления и другие правила аномалий, устойчивость сети при удалении узлов, граница наблюдения и рекомендации по недостающим данным.
• Публикация каталога запуска с run_id, JSON-снимком, CSV, метаданными и отчётом качества.

Дополнительные анализы доступны через API и отдельный экран /analysis-extras при запуске через ai_agent; не все они встроены в основной React-dashboard.

AI-помощник

• Чат в основном сайте: вопросы о приоритетах, узлах, соседях, путях и других доступных фактах снимка; переход из ответа к GID и просмотр вызванных инструментов.
• OpenAI Responses API с 16 инструментами только для чтения. Модель не пересчитывает роли и не изменяет результаты анализа.
• Без настроек OpenAI или при ошибке провайдера используется помеченный локальный режим fallback для поддерживаемых типов вопросов. Это разбор по правилам и фактам, не ответ LLM.
• Ограничения времени и числа вызовов, проверки GID и числовых утверждений, предупреждения о неполных результатах. Эти проверки не гарантируют истинность каждого предложения.

Telegram-бот и Mini App

• Отдельный Python-бот @FreedomGraphbot: личная активация кодом команды, автоматическая подписка, статус, пауза, возобновление и отключение.
• Сравнение опубликованных backend-снимков и уведомления о впервые наблюдаемых направленных связях в сопоставимом срезе. Первый снимок создаёт базу без рассылки. Это не предсказание будущих связей и не поток банковских операций в реальном времени.
• Подписки, очередь и история доставок — в локальной SQLite. По умолчанию разрешены только синтетические снимки, GID и суммы в сообщениях скрыты.
• Mini App: мобильный интерфейс в тёмно-фиолетовой теме, RU / KZ / EN, сигналы, фильтры, граф и объяснения.
• Mini App пока использует синтетические данные из data.mjs. Отметки проверки сохраняются только в браузерной сессии и не синхронизируются с ботом или backend. Серверная авторизация Mini App не реализована.

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

1. Команда помещает nodes.parquet, edges.parquet, transactions.parquet в backend/data/ и запускает pipeline.
2. Graph Engine проверяет входы, рассчитывает роли, кластеры, приоритеты и объяснения. Backend публикует согласованный снимок.
3. Аналитик открывает сайт, выбирает приоритетный узел или вводит полный GID. Интерфейс показывает окружение и карточку с основаниями.
4. Аналитик изучает направление, суммы и даты связей, проверяет структурную цепочку и ограничения хронологии. При необходимости задаёт вопрос помощнику.
5. Факты добавляются в досье. На выходе — PDF- или Markdown-отчёт с run_id, направлениями, суммами, датами и оговорками либо CSV результатов.

Цепочка показывает достижимость в графе. Суммы её рёбер нельзя автоматически складывать в «сумму прошедших по цепочке денег».

4. Технологии

Компонент	Технологии
Основной frontend	React, TypeScript, Vite, Cytoscape.js, lucide-react, CSS; lockfile: Frontend/package-lock.json
API и публикация результатов	Python, FastAPI, Uvicorn, Pydantic, python-dotenv, ReportLab для PDF, файловые снимки JSON/CSV
Графовая аналитика	pandas, NumPy, NetworkX, SciPy, PyArrow, PyYAML
AI-помощник	Python SDK OpenAI, Responses API, function calling; модель задаётся OPENAI_MODEL
Telegram-бот	Python standard library, Telegram Bot API, SQLite, long polling
Telegram Mini App	HTML, CSS, JavaScript ES-модули, SVG, Telegram WebApp SDK; без npm-сборки
Проверки	unittest, pytest, Node.js test runner, TypeScript

В репозитории есть отчёт проверки агента с моделью gpt-4.1-mini. Это модель указанного прогона, а не автоматически выбираемая модель всех установок. NVIDIA и другие LLM-провайдеры в текущей реализации не подключены.

5. Архитектура

Три Parquet-файла
        │
        ▼
backend.run_pipeline → graph.analyze → роли, признаки, кластеры, extras
        │
        ▼
backend/output/runs/<run_id>/ + LATEST
        │
        ▼
FastAPI /api/v1
        ├── React-dashboard → карточки, граф, досье, CSV
        ├── AI-помощник → инструменты снимка → OpenAI или локальный fallback
        └── Telegram-бот → сравнение снимков → личные уведомления

Telegram Mini App → свои синтетические данные (пока отдельно от API)

Каталог	Назначение
Frontend/	Основной сайт и готовая сборка dist/
backend/	Pipeline, API, публикация снимков и экспорт
graph/	Аналитика, методика, валидация и extras/
ai_agent/	Агент, интеграция и отдельные экраны
TelegramBot/	Бот, локальная конфигурация и состояние
TelegramBot/miniapp/	Независимая frontend-демонстрация Mini App

graph.analyze() сам не записывает файлы и не обращается к сети. Публикацией занимается backend. API использует один загруженный снимок до явного перечитывания. GID в JSON — строки: преобразование в JavaScript Number может потерять точность.

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

Команды выполняются из корня репозитория, если не указано иначе. Нужны Git, доступ к репозиторию и Python 3.11+; проверенные окружения описаны в документации модулей. Для первого получения зависимостей нужен интернет.

6.1. Получить код и зависимости

git clone https://github.com/BAITC-Hacks/hack-0b94fdb6-ascend.git
cd hack-0b94fdb6-ascend

Если рабочая копия уже есть, обновите её, предварительно сохранив свои изменения; не клонируйте поверх существующей папки.

Windows / PowerShell:

py -m venv backend/.venv
.\backend\.venv\Scripts\python.exe -m pip install -r backend/requirements-assistant.txt

macOS / Linux:

python3 -m venv backend/.venv
backend/.venv/bin/python -m pip install -r backend/requirements-assistant.txt

Набор включает API, Graph Engine и SDK агента. Установка SDK сама по себе не включает платные обращения к OpenAI. Готовая сборка Frontend/dist/ включена в Git: для обычного запуска основного сайта Node.js не требуется.

6.2. Запуск на данных кейса

Выданные организаторами файлы включены в репозиторий в следующей структуре:

backend/data/nodes.parquet
backend/data/edges.parquet
backend/data/transactions.parquet

Windows:

.\backend\.venv\Scripts\python.exe -m backend.run_pipeline
.\backend\.venv\Scripts\python.exe -m backend.serve

macOS / Linux:

backend/.venv/bin/python -m backend.run_pipeline
backend/.venv/bin/python -m backend.serve

Откройте основной сайт или диагностику. Схема API — openapi.json; Swagger UI /docs в текущем backend отключён.

Терминал сервера должен оставаться открытым. Остановка — Ctrl+C. По умолчанию сервер доступен только с того же компьютера через 127.0.0.1.

Три исходных файла и готовый расчёт backend/jury_snapshot/ входят в Git. Чтобы открыть готовый расчёт без повторного pipeline, используйте jury_start.py по инструкции жюри. Локальные пересчёты в backend/output/ и секретные настройки остаются вне Git.

Если pipeline выполнен при уже работающем сервере, на /check нажмите «Перечитать результат» (POST /api/v1/reload), затем обновите данные сайта. Кнопка обновления сайта сама по себе не пересчитывает граф и не выполняет reload API.

6.3. Запуск без исходных данных

Windows:

.\backend\.venv\Scripts\python.exe -m backend.run_pipeline --demo
.\backend\.venv\Scripts\python.exe -m backend.serve --demo

macOS / Linux:

backend/.venv/bin/python -m backend.run_pipeline --demo
backend/.venv/bin/python -m backend.serve --demo

Демо содержит 24 синтетических изолированных узла и 0 связей. Оно проверяет запуск, карточки, поиск и CSV, но не демонстрирует транзакционные цепочки. Пустые связи здесь ожидаемы. Ошибка анализа настоящих данных не подменяется демо автоматически.

Перед сменой режима остановите предыдущий сервер. Результаты демо находятся отдельно в backend/output-demo/.

6.4. OpenAI — необязательно

Создайте локальный backend/.env по backend/.env.example, если его ещё нет. Для AI заполните:

ASSISTANT_ENABLED=1
OPENAI_API_KEY=<ваш_секретный_ключ>
OPENAI_MODEL=<доступная_вашему_проекту_модель>

Значения в угловых скобках — заглушки. Нужна модель с поддержкой используемого Responses API и вызовов инструментов. После изменения настроек перезапустите backend.serve. Ключ не вводится в frontend и не коммитится.

Вопрос, до шести предыдущих сообщений и выбранные результаты инструментов могут передаваться OpenAI; обращения могут тарифицироваться. Без настройки OpenAI основные расчёты и сайт работают локально, помощник использует fallback. Значение assistant_enabled в health характеризует настройку провайдера, но не проверяет баланс или доступность модели.

6.5. Дополнительные экраны аналитики

Чтобы открыть /assistant и /analysis-extras, после расчёта используйте альтернативную точку входа на порту 8001:

# Windows
.\backend\.venv\Scripts\python.exe -m ai_agent --output backend/output --port 8001

# macOS / Linux
backend/.venv/bin/python -m ai_agent --output backend/output --port 8001

Этот процесс также предоставляет backend и основной сайт. Для OpenAI здесь нужно явно передать --env-file ai_agent/.env с тремя AI-настройками из инструкции агента; backend/.env автоматически не загружается. В старом снимке без extras новые анализы отсутствуют — требуется пересчёт текущим Graph Engine.

6.6. Разработка frontend

Нужны Node.js и npm, совместимые с установленной версией Vite. Из корня:

cd Frontend
npm ci
npm run dev

Vite проксирует /api на 127.0.0.1:8000: backend запускается отдельно. Адрес frontend показывает терминал Vite. Для обновления поставляемой сборки выполните npm run build; результат записывается в Frontend/dist/.

При отдельном API-адресе перед сборкой задайте VITE_API_BASE_URL и согласуйте CORS. Любые VITE_* доступны браузеру и не подходят для секретов.

6.7. Telegram и Mini App

Это дополнительные компоненты; для основного сайта они не требуются.

• Запуск бота на macOS/Linux из корня: python3 -m TelegramBot.launch. Первая настройка запросит токен скрытым вводом и создаст локальную конфигурацию. На Windows для текущего бота нужен WSL/Linux из-за fcntl.
• В TelegramBot/.env задаются BACKEND_URL, MINIAPP_URL и параметры уведомлений. backend/.env не заменяет конфигурацию бота.
• Не запускайте одновременно два процесса одного токена. При переносе отдельно передаются конфигурация и SQLite; они не входят в Git.
• Локальный Mini App: python3 -m http.server 5175 --bind 127.0.0.1 --directory TelegramBot/miniapp (на Windows можно использовать py). Открыть http://127.0.0.1:5175/.
• Внутри Telegram нужен публичный HTTPS-адрес. Публикация и перенос описаны в README Mini App.

Не публикуйте .env, токены, код активации команды и TelegramBot/state/. Опубликованный ранее код активации нельзя считать секретом: перед использованием с ограниченным доступом его нужно заменить. Разрешение настоящих снимков через ALLOW_REAL_DATA=1 допустимо только после согласования передачи данных; это не настройка по умолчанию.

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

На данных кейса — основной сценарий

1. Выполните быстрый запуск или раздел 6.2 для самостоятельного пересчёта. На /check проверьте успешный run_id, отсутствие синтетической пометки и доступность CSV.
2. На сайте выберите первый приоритетный узел, скопируйте полный GID и найдите его через поиск. Проверьте роль, вход/выход, кластер и evidence.
3. Откройте связь через граф или «Расследование» → «Связи». Проверьте источник, получателя, сумму, количество переводов и диапазон дат.
4. В разделе «Цепочка» укажите два GID с направленным путём. Изучите результат и сообщение о хронологии; отсутствие противоречия не доказывает передачу одних и тех же денег.
5. Добавьте узел, связь и путь в досье, нажмите «Скачать PDF» или сохраните .md. Проверьте факты, run_id и ограничения. Сопоставьте выбранный узел с CSV.
6. В «Спросить AI» отправьте «Выбери 10 приоритетных узлов» или «Объясни роль узла #<GID>». Проверьте режим ai / fallback, ссылки на узлы и перечень инструментов.

В репозитории есть сценарий на 3–4 минуты с конкретными GID, привязанный к снимку 20260923T093020Z-77346e52. Он подходит для соответствующих исходных данных; на другом наборе ожидания могут отличаться.

По зафиксированной проверке Graph Engine исходный набор содержит 2 248 узлов, 3 119 рёбер, 4 840 транзакций; получен 91 кластер. Это показатели конкретного набора, а не фиксированные значения интерфейса и не гарантия для произвольных входов.

Без данных кейса

Выполните раздел 6.3, найдите GID 900000000000000000, откройте карточку и CSV. Ожидаются синтетическая пометка, роль peripheral и отсутствие рёбер. Для проверки цепочек нужны данные кейса или автоматические тесты, а не этот smoke-test.

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

Следующие Python-команды выполняются Python из созданного окружения: backend/.venv/bin/python на macOS/Linux или .\backend\.venv\Scripts\python.exe на Windows. Ниже он обозначен как python.

python -m pip install -r graph/requirements-dev.txt
python -m pytest graph/tests ai_agent/tests backend/tests -q
python -m unittest TelegramBot.test_bot -v

Приёмочные тесты настоящих данных требуют локальных Parquet и могут пропускаться без них. Пропуск — не успешный анализ. Тесты с подставным провайдером не подтверждают работу живой модели. Живая оценка вынесена в инструкцию AI и может расходовать API-кредиты.

Для следующих тестов .ts нужен Node.js с поддержкой прямого выполнения TypeScript (например, использованный при локальной проверке Node.js 26):

node --test Frontend/tests/graphView.test.mjs Frontend/tests/flowAnimation.test.mjs Frontend/tests/investigation.test.mjs TelegramBot/miniapp/test.mjs

При подготовке комплекта 23.09.2026 прошли 17 Node.js-тестов интерфейса/Mini App и 80 тестов Graph/AI; TypeScript и сборка frontend — без ошибок. Приёмка комплекта на данных организаторов находится в backend/tests/test_jury_bundle.py: проверяет файлы, API, CSV, PDF, локальный помощник и Mini App. Для неё не нужны личные ключи.

Отдельные отчёты команды: Graph Engine, дополнительные анализы, агент. Это не заявление о завершённой сквозной приёмке всех компонентов.

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

Вход	Обязательные поля
nodes.parquet	gid, depth, is_seed
edges.parquet	src, dst, sum_kzt, n_tx, depth
transactions.parquet	src, dst, date, sum_kzt

Источник — файлы кейса организаторов, включённые в backend/data/ для проверки жюри. Прямой коннектор к банковской системе, потоковому источнику или внешним реестрам не реализован. Проверяются точность идентификаторов, уникальность пар рёбер, допустимость дат и положительных сумм, согласованность рёбер с числом и суммами транзакций.

Основные запросы: /api/v1/health, /overview, /graph, /nodes, /nodes/{gid}, /nodes/{gid}/neighbors, /subgraph, /top, /clusters, /clusters/{id}, /export/{name}, /assistant. Все сокращённые пути в этом перечне начинаются с /api/v1. Дополнительные маршруты описаны в документации extras.

Внешние сервисы — OpenAI для необязательных AI-ответов и Telegram для бота/Mini App. Локальная графовая аналитика не требует внешней LLM или GPU. GitHub передаёт исходники, но не выполняет Python-приложение.

9. Ограничения и безопасность

• Неполный срез. По методике кейса не видны межбанковские переводы, остатки, атрибуты клиентов и операции ниже порога наблюдения 5 000 KZT. У seed неполные входящие; на глубине 4 исходящие не прослежены. Отсутствие наблюдений не равно отсутствию активности.
• Гипотезы, не диагноз. Роли, аномалии, кластеры и приоритеты рассчитаны правилами. Размеченной выборки для заявления accuracy нет. Название уровня приоритета в UI не является вероятностью нарушения.
• Временная точность. Вход содержит календарную дату без времени суток. Связи главного графа агрегированы; хронология пути и FIFO-анализ не доказывают принадлежность денег конкретному маршруту.
• Масштаб. Используются NetworkX и снимки в памяти; работа на миллионе узлов не реализована и не подтверждена. Браузер ограничивает отображение и анимацию, но всё равно загружает полный снимок графа.
• Сохранение работы. Досье основного сайта сбрасывается при перезагрузке/смене снимка и требует выгрузки для сохранения. Нет общего хранилища расследований и совместного редактирования.
• AI. Локальный fallback понимает ограниченные типы вопросов. Проверки ответа модели не доказывают корректность всей интерпретации. Перед внешним вызовом требуется разрешение на передачу выбранных фактов провайдеру.
• Telegram. Нужны работающий бот и доступные согласованные снимки. Первый снимок и новый несопоставимый срез не запускают массовую рассылку старых связей. Доставка не обещает exactly-once: при потере сетевого подтверждения возможен повтор.
• Mini App. Нет реальных сигналов, синхронизации с ботом и серверной проверки Telegram initData. Публичная кнопка Mini App сама по себе не подтверждает полномочия аналитика.
• Не банковский production. В основном API нет полноценной аутентификации, разграничения доступа, SSO, защищённого многопользовательского контура и полного аудита. Не выставляйте API и клиентские данные в открытый интернет без отдельной защиты. Секреты и закрытые данные не должны попадать в Git.
• Общая приёмка. Модульные тесты не подтверждают цепочку «новый backend-снимок → уведомление → реальные данные Mini App». Последний этап Mini App ещё не реализован.

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

Постоянный публичный адрес общей версии пока не настроен. Для воспроизводимой проверки используйте JURY.md. Для размещения подготовлены Dockerfile, compose.yaml и render.yaml. Адрес 127.0.0.1 доступен только на машине сервера и не является ссылкой для удалённого жюри.

Ранее настроенный временный HTTPS-туннель относится только к демонстрационному Mini App, зависит от работающего ноутбука и не заменяет размещение всего проекта. Его адрес не указан здесь как стабильная ссылка решения. Инструкция для публикации Mini App — в его README.

11. Документация по компонентам

• Backend: запуск, API и публикация результатов.
• Graph Engine: правила ролей и приоритетов, дополнительные анализы.
• AI-агент: настройка, инструменты и проверки.
• Сценарий демонстрации основного сайта.
• Telegram Mini App: запуск, ограничения и передача тимлиду.

Некоторые ранние инструкции модулей описывают предыдущие этапы разработки. Этот README отражает текущие точки входа и разделяет основной сайт с API, необязательный AI и независимую демонстрацию Mini App.