Пошаговое руководство по курсу

Для кого: разработчики, строящие доверие агентов, репутацию и аудит системного риска на оракулах AIMarket.
Язык лаб: COURSE_LANG=en|ru|es|fr|zh · строки UI в i18n/ · этот гайд на русском. English · Español · Français · 中文

Сверка с текущей экосистемой

Сравните учебный граф PageRank с публичным снимком пиров Hub. Для сравнения используйте строки одобренных пиров и отдельно держите ожидающие предпросмотры. Запишите дату наблюдения, входной граф и правило выбора рёбер. Рейтинг описывает этот граф. Допуск и проверка ключа подписи выполняются отдельно.

Зачем этот курс

Мультиагентные системы постоянно отвечают на один вопрос: какому агенту (или агрегату, или маршруту) я доверяю — и могу ли я это доказать? Курс превращает этот вопрос в математику, которую можно запустить. Пять живых оракулов AIMarket считают сигналы — LUMEN (PageRank/EigenTrust), PERCOLA (пороги перколяции), FOURIER (спектральная связность), MURMURATION (устойчивый консенсус) и ABLATION (каскадный риск кучи песка) — и каждый сигнал приходит со своим сертификатом проверки, так что верить оракулу на слово не нужно. Лабы детерминированы и работают на NumPy: для базового трека не нужны ни API-ключи, ни сеть.

К концу вы умеете оценивать граф «кто кому доверяет», находить ключевой узел, удаление которого раскалывает граф, измерять, насколько граф близок к расколу, агрегировать шумные прогнозы против злоумышленника и оценивать риск хвоста системного каскада — а затем складывать всё это в один проверяемый аудит доверия.

Выбор трека

Трек	Модули	Время	Оракулы
Базовый	M1 → M2 → M3 → M4	~2 ч	LUMEN, PERCOLA, FOURIER, MURMURATION
Продвинутый	Базовый + M5 каскад	+30 мин	+ ABLATION (куча песка)
Итоговый	M6 сводный аудит	+20 мин	LUMEN + FOURIER + PERCOLA вместе

Лаб шесть (labs/lab01–lab06), по одной на модуль. Каждая печатает блок Trace (трейс) — это её журнал аудита. Лабы с проверяемым оракулом печатают ещё и verify: True — результат независимо перепроверен, а не просто заявлен.

Установка (10 минут)

Шаг 1 — Клон и установка

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/mathematics-of-trust-course
pip install -e ".[oracles,dev]"

Из монорепозитория aicom (рекомендуется контрибьюторам):

cd courses/mathematics-of-trust-course
pip install -e ".[oracles,dev]"

Все пять оракулов подхватываются автоматически из oracles/oracles/* при запуске внутри монорепо.

Отдельный клон без соседнего монорепо:

git clone --depth 1 https://github.com/alexar76/oracles.git _deps/oracles
for pkg in lumen murmuration fourier percola ablation; do
  pip install -e _deps/oracles/oracles/$pkg
done
pip install -e ".[oracles,dev]"

Шаг 2 — Тесты

pytest -q

Ожидается: паритет i18n, интеграция с оракулами доверия, упражнения, smoke-импорт лаб.

Шаг 3 — Язык интерфейса лаб

export COURSE_LANG=ru   # или es, по умолчанию en
python labs/lab01_keystone_nodes.py

Шаг 4 — Google Colab

Откройте сайт курса → Open in Colab на любой лабе.
Выполните setup-ячейку (clone + pip + срез оракулов).
При необходимости: os.environ["COURSE_LANG"] = "ru".
Запустите ячейку лабы.

M1 — EigenTrust на LUMEN

Концепция: стационарное распределение PageRank на графе «кто кому доверяет».
Лаба: labs/lab02_trust_pagerank.py · ~20 мин · нужна установка

Шаги

python labs/lab02_trust_pagerank.py
Посмотрите учебный граф в courselib/trust.py — demo_trust_graph().
Ранжированные оценки: hub и хорошо связанные агенты должны быть выше периферии.
Загляните в oracles/oracles/lumen/lumen/pagerank.py — ядро EigenTrust (5 мин).
Упражнение: python labs/run_exercises.py --module m1.

Самопроверка

[ ] Оценки в сумме дают 1 (распределение вероятностей)
[ ] Транзитивное доверие поднимает узлы, которым доверяют доверенные узлы

M2 — Перколяция и ключевые узлы

Концепция: целенаправленное удаление узлов и критические пороги на графах доверия.
Лаба: labs/lab01_keystone_nodes.py · ~20 мин · нужна установка

Шаги

python labs/lab01_keystone_nodes.py
Следите за f_c — критической долей узлов, удаление которых обрушивает связность.
Изучите keystones (ключевые узлы) — мосты между двумя кликами (3, 4, 8 в учебном графе).
Подтвердите verify: True — PERCOLA пересчитывает порог, не доверяя оракулу на слово.
Упражнение: python labs/run_exercises.py --module m2.

Самопроверка

[ ] Понимаете, почему мостовой узел — ключевой
[ ] Проверка проходит без повторного полного перебора Монте-Карло

M3 — Спектральная связность

Концепция: значение Фидлера и спектральная бисекция — насколько граф близок к расколу?
Лаба: labs/lab03_spectral_cut.py · ~20 мин · нужен M1 или M2

Шаги

python labs/lab03_spectral_cut.py
Читайте λ₂ (значение Фидлера) — малые значения = узкое «бутылочное горло».
Изучите спектральный разрез — множества A и B и проводимость (conductance).
Откройте oracles/oracles/fourier/fourier/spectral.py — analyze() и verify() (5 мин).
Упражнение: python labs/run_exercises.py --module m3.

Самопроверка

[ ] Сертификат собственной пары Фидлера проверяется за O(E)
[ ] Проводимость показывает, насколько «дорогой» разрез

M4 — Устойчивый консенсус

Концепция: медиана, усечённое среднее и biweight-оценка положения по прогнозам агентов.
Лаба: labs/lab04_consensus_aggregate.py · ~15 мин · нужна установка

Шаги

python labs/lab04_consensus_aggregate.py
Сравните наивное среднее, медиану и biweight на demo_agent_estimates() (один выброс на 500).
Загляните в murmuration/consensus.py — точки слома (breakdown points) и число итераций DeGroot.
Упражнение: python labs/run_exercises.py --module m4.

Самопроверка

[ ] Медиана и biweight устойчивы к злонамеренному выбросу
[ ] DeGroot сходится к арифметическому среднему на полном графе

M5 — Каскадный риск

Концепция: лавины абелевой кучи песка и степенной риск хвоста.
Лаба: labs/lab05_sandpile_cascade.py · ~30 мин · нужны M1–M4

Шаги

python labs/lab05_sandpile_cascade.py
Изучите τ (показатель степенного закона), максимальную лавину и CVaR 99%.
Прочитайте топ узлов-триггеров — кто чаще всего запускает крупные каскады.
Подтвердите verify: True — суммарное число обрушений и τ воспроизводятся бит-в-бит.
Упражнение: python labs/run_exercises.py --module m5.

Самопроверка

[ ] Размеры лавин не зависят от порядка (абелево свойство)
[ ] Тяжёлый хвост (малое τ) сигналит о системном риске заражения

M6 — Итоговый проект: математика доверия

Концепция: объединить сигналы PageRank, спектра и перколяции в один проверяемый аудит доверия.
Лаба: labs/lab06_trust_audit.py · ~20 мин · нужны M1–M3

Шаги

python labs/lab06_trust_audit.py
Прочитайте однострочный аудит по demo_trust_graph():
- Самый доверенный узел и его оценка PageRank (LUMEN) — ожидается hub.
- Алгебраическая связность λ₂ и её флаг verify от FOURIER.
- Порог перколяции f_c и его флаг verify от PERCOLA.
- Ключевые узлы, связывающие граф мостами.
Подтвердите итоговый verify: True — это И (AND) сертификатов спектра и перколяции. Одно проваленное доказательство проваливает весь аудит.
Откройте courselib/trust.py — trust_audit_summary(): вызывает score_pagerank, analyze_spectral и analyze_percolation, затем возвращает top_trusted, fiedler_value, percolation_f_c, keystones и оба флага проверки.
Набросайте, как бы вы пропускали действие агента сразу по трём сигналам (доверенный источник и связный граф и отсутствие хрупких ключевых узлов).
Упражнение: python labs/run_exercises.py --module m6.

Ожидаемый вывод

Строка == Trust math capstone ==
Trust audit (7 nodes) с самым доверенным = hub, λ₂, f_c и ключевыми узлами
Итоговый verify: True

Самопроверка

[ ] Называете три оракула, из которых собран аудит (LUMEN, FOURIER, PERCOLA)
[ ] Понимаете, почему аудит проходит только когда проходит каждый сигнал

Упражнения и сертификат

После лаб запустите проверки:

python labs/run_exercises.py
python labs/run_exercises.py --certificate "Иван Петров" --lang ru

Модуль	Что проверяет упражнение
M1	Оценки PageRank в сумме дают 1
M2	Ключевые узлы найдены; проверка PERCOLA проходит
M3	Сертификат Фидлера проверяется
M4	Консенсус устойчив к выбросу
M5	τ каскада и суммарное число обрушений проверяются
M6	Сводный аудит: `hub` самый доверенный, доказательства спектра и перколяции проходят

Сертификат покрывает все шесть модулей. HTML открывается в браузере; Print → Save as PDF для версии, которой можно поделиться. ID сертификата — sha256(имя|дата)[:12], поэтому одно и то же имя в один и тот же день всегда даёт один и тот же ID. Чтобы перегенерировать без перезапуска проверок, добавьте --skip-check; путь задаётся через -o path/to/certificate.html.

Наблюдаемость в каждой лабе

Концепция: каждая лаба пишет решения в Trace (трейс) — это ваш журнал аудита событий доверия.

Шаги (после каждой лабы)

Прокрутите к секции trace в конце вывода.
Сопоставьте события со stdout: оценки доверия, пороги перколяции, спектральные значения, статистики консенсуса, метрики каскада.
В M5 свяжите события cascade с напечатанными τ и CVaR.

Самопроверка

[ ] Трейс — это «превью SIEM» для математики доверия
[ ] Можете указать флаг проверки для каждого вызова оракула

Мост: от курса к боевым оракулам

Цель: связать концепции курса с живыми деплоями оракулов AIMarket (~30 мин).

Прочитайте README оракулов в oracles/oracles/{lumen,percola,fourier,murmuration,ablation}/.

Сопоставление курс → возможности оракула

Курс	Оракул	Возможность
M1	LUMEN	`lumen.pagerank@v1`
M2	PERCOLA	`percola.threshold@v1` + `percola.verify@v1`
M3	FOURIER	`fourier.spectrum@v1` + `fourier.verify@v1`
M4	MURMURATION	`murmuration.aggregate@v1`
M5	ABLATION	`ablation.cascade@v1` + `ablation.verify@v1`
M6	LUMEN + FOURIER + PERCOLA	сводный аудит (`trust_audit_summary`)

Вызов через Hub (опционально, из монорепо):
```
cd aimarket-hub && pytest -q -k lumen
```

Чеклист самопроверки

Базовый трек:

[ ] lab01–lab04 локально и в Colab
[ ] Объясняете PageRank-доверие на графе «кто кому доверяет»
[ ] Называете ключевые узлы на графе-мосте
[ ] Интерпретируете значение Фидлера и проводимость
[ ] Выбираете медиану vs среднее для злонамеренных прогнозов агентов

Продвинутый трек:

[ ] lab05 + объяснение риска хвоста кучи песка
[ ] lab06 и trust_audit_summary(); объясняете, почему аудит проходит только когда проходит каждый сигнал

Типичные проблемы

Проблема	Решение
`ModuleNotFoundError: courselib`	Запуск из корня репозитория; лабы добавляют родителя в `sys.path`
`ImportError: Oracle package 'lumen'`	Установите срез оракулов или запускайте из монорепо aicom
Нет `numpy`	`pip install -e ".[oracles,dev]"`
Пустые строки RU/ES	`export COURSE_LANG=ru`; ключи `i18n/ru.json` должны совпадать с `en.json`
Падает i18n в pytest	Добавьте недостающие ключи во все три JSON
Проверка PERCOLA не проходит	`samples` должен совпадать в analyze и verify
Старый код в Colab	Перезапустите setup-ячейку; закрепите ветку `main`

Обновление сайта и ноутбуков

После правок лаб или i18n:

python3 scripts/build_course_assets.py
python3 scripts/labs_to_notebooks.py

Гайды в docs/ правятся вручную — сначала EN, затем зеркала RU/ES.