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

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

---

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

Сравните учебный граф PageRank с [публичным снимком пиров Hub](https://modelmarket.dev/ai-market/v2/federation/peers). Для сравнения используйте строки одобренных пиров и отдельно держите ожидающие предпросмотры. Запишите дату наблюдения, входной граф и правило выбора рёбер. Рейтинг описывает этот граф. Допуск и проверка ключа подписи выполняются отдельно.

---

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

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

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

---

## Содержание

1. [Выбор трека](#выбор-трека)
2. [Установка (10 минут)](#установка-10-минут)
3. [M1 — EigenTrust на LUMEN](#m1--eigentrust-на-lumen)
4. [M2 — Перколяция и ключевые узлы](#m2--перколяция-и-ключевые-узлы)
5. [M3 — Спектральная связность](#m3--спектральная-связность)
6. [M4 — Устойчивый консенсус](#m4--устойчивый-консенсус)
7. [M5 — Каскадный риск](#m5--каскадный-риск)
8. [M6 — Итоговый проект: математика доверия](#m6--итоговый-проект-математика-доверия)
9. [Упражнения и сертификат](#упражнения-и-сертификат)
10. [Наблюдаемость в каждой лабе](#наблюдаемость-в-каждой-лабе)
11. [Мост: от курса к боевым оракулам](#мост-от-курса-к-боевым-оракулам)
12. [Чеклист самопроверки](#чеклист-самопроверки)
13. [Типичные проблемы](#типичные-проблемы)

---

## Выбор трека

| Трек | Модули | Время | Оракулы |
|------|--------|-------|---------|
| **Базовый** | 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 — Клон и установка

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

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

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

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

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

```bash
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 — Тесты

```bash
pytest -q
```

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

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

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

### Шаг 4 — Google Colab

1. Откройте [сайт курса](https://alexar76.github.io/aimarket-courses/mathematics-of-trust-course/) → **Open in Colab** на любой лабе.
2. Выполните setup-ячейку (clone + pip + срез оракулов).
3. При необходимости: `os.environ["COURSE_LANG"] = "ru"`.
4. Запустите ячейку лабы.

---

## M1 — EigenTrust на LUMEN

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

### Шаги

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

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

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

---

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

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

### Шаги

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

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

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

---

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

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

### Шаги

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

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

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

---

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

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

### Шаги

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

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

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

---

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

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

### Шаги

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

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

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

---

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

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

### Шаги

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

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

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

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

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

---

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

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

```bash
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` (трейс) — это ваш журнал аудита событий доверия.

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

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

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

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

---

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

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

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

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

   | Курс | Оракул | Возможность |
   |------|--------|-------------|
   | 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`) |

3. **Вызов через Hub** (опционально, из монорепо):

   ```bash
   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:

```bash
python3 scripts/build_course_assets.py
python3 scripts/labs_to_notebooks.py
```

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