# Задание Павленко Богдану Викторовичу

## 1. Трек

Condition-Aware RGB-Anchored Fusion.

Дополнительная командная роль: владелец общего fusion API и архитектурной совместимости трёх реализаций.

## 2. Исследовательский вопрос

Может ли controller, использующий RGB content summary и признаки качества auxiliary inputs, динамически выбирать полезный вклад text, segmentation и geometry, сохраняя надёжный RGB residual path?

## 3. Обязательное чтение

### Общий пакет

- `docs/02_references/01_required/`
- `docs/02_references/02_fusion_core/СИНТЕЗ_3_fusion.md`
- `docs/02_references/02_fusion_core/SPEC_fusion_ACF_MERIDIAN_v5.md`
- `docs/02_references/02_fusion_core/ANALYSIS_FiLM_alternatives_taxonomy_v4.md`
- `docs/02_references/06_paper_analyses/B14_BB_2025_Strip R-CNN Large Strip Convolution for Remote Sensing Object Detection.md`

### Персональный пакет

- `F39_2025_CAFuser_Condition-Aware_Multimodal_Fusion.md`
- `F37_2024_AsymFormer_Asymmetrical_Cross-Modal_Mobile_RGB-D.md`
- `F43_2024_Robust_Multimodal_Missing_Modalities_PEFT.md` — peer-reviewed (TPAMI 2024) опора identity-adapters и missing-modality поведения
- `F40_2025_M3amba_CLIP-driven_Mamba_Multi-modal_RS.md`
- `F4_2025_EARTHMIND ... MULTIMODAL LLM.md`
- `F44_2025_Fusion-Mamba_Cross-modality_Object_Detection.md`
- `F68_2024_RemoteDet-Mamba_Hybrid_RS.md`
- `F47_2026_TacFiLM_Tactile_Modality_Fusion_VLA.md`

Файлы находятся внутри `docs/02_references/06_paper_analyses/` и `05_text/`.

### Канонические опоры (проверенные выводы из vault, использовать в evidence matrix)

| Источник | Факт | Следствие для трека A |
|---|---|---|
| C5 WeatherPrompt (NeurIPS 2025), `05_text/` | Dynamic Gate 80.20 > Concat 78.90 > Static gate 78.45 | веса fusion должны быть instance-conditioned — прямой аргумент за controller |
| F14 WeatherPrompt deep dive | FiLM 73.37% > CrossAttn 68.10% > Concat 62.50%; спецификация text→FiLM MLP: zero-init, two-speed LR, EMA | готовый рецепт text-пути и инициализации |
| Flamingo (NeurIPS 2022, см. TRIAGE §1) | zero-init tanh(α)-gated cross-attention: при α=0 модель ≡ frozen base | корень линии identity-at-init; цитировать как первоисточник |
| F39 CAFuser (RA-L 2025) | condition token строится из RGB и управляет fusion остальных модальностей | каноничный шаблон трека |
| TRIAGE §6a, вывод 1 | gated additive residual — dropout-safe; чисто multiplicative gating ломается при near-zero aux | residual-форма обязательна для primary |

## 4. Общая обязанность: fusion API

Совместно с коллегами определить и реализовать:

```python
class FusionModelBase(nn.Module):
    def encode_view(self, batch: ViewBatch, view: ViewName) -> FusionViewOutput:
        ...
```

API должен:

1. принимать одинаковый batch для всех variants;
2. различать satellite CHM и UAV depth через `view`;
3. возвращать descriptor и diagnostics;
4. не требовать paired-view features;
5. поддерживать batch size 1;
6. быть пригодным для unit tests;
7. позволять registry/factory выбирать variant через gin.

До merge API получить согласие Близно и Мороза.

## 5. Персональные задачи

### A0. Evidence matrix

Создать таблицу минимум по восьми источникам:

| Source | Original task | Fusion operator | Conditioning signal | Identity path | Transfer to StripNet | Risk |
|---|---|---|---|---|---|---|

Для каждого source отдельно отметить paper fact и собственное предположение.

### A1. Определить RGB anchor

Сравнить возможные content summaries:

1. GAP stage 3.
2. GAP stage 4.
3. Concatenated GAP stages 3-4.
4. Lightweight attention pooling stage 4.

Выбрать primary summary. Обосновать, почему он содержит достаточно информации для выбора modality contribution.

### A2. Определить quality signals

Минимальный набор кандидатов:

| Modality | Возможные quality features |
|---|---|
| Text | empty mask, token count, text norm, caption quality score |
| Segmentation | entropy, background fraction, class diversity, valid fraction |
| CHM | valid fraction, dynamic range, gradient energy |
| Depth | valid fraction, dynamic range, smoothness/gradient consistency |

Не включать все признаки автоматически. Выбрать признаки, которые можно вычислить стабильно и без labels test split.

### A3. Спроектировать auxiliary paths

Для каждой modality определить:

- raw tensor;
- normalization;
- encoder;
- output channel dimension;
- target StripNet stage;
- residual transform;
- initialization;
- validity handling.

CHM и depth используют раздельные input projectors, даже если после них общий interface.

### A4. Сформировать три кандидата

| Candidate | Required design |
|---|---|
| A-C1 | channel-wise gated additive residual |
| A-C2 | multi-stage FiLM с condition-aware gates |
| A-C3 | dense residual paths для maps + token cross-attention для text |

Для каждого рассчитать:

- insertion stages;
- trainable params;
- dominant operations;
- expected VRAM;
- identity preservation;
- modality attribution;
- главный failure mode.

### A5. Выбрать primary и fallback

Рекомендуемый scoring template:

| Criterion | Weight |
|---|---:|
| Retrieval fit | 25 |
| RGB preservation | 20 |
| Modality attribution | 15 |
| Compute | 15 |
| Stability | 15 |
| Implementation risk | 10 |

### A6. Формализовать controller

Минимальная формула:

```math
c_v = Controller([Pool(X_v^{rgb}); q_v^{text}; q_v^{seg}; q_v^{geom}; e_v^{view}])
```

```math
X_v^{l,new} = X_v^{l,rgb} + sum_m a_{v,m}^{l} * Delta_{v,m}^{l}
```

Нужно определить:

- scalar, channel или spatial gates;
- sigmoid или softmax;
- конкурируют ли модальности за единичную массу;
- contribution cap;
- zero-init residual;
- regularization, если она действительно нужна;
- **поведение при validity = 0**: gate невалидной модальности обязан давать нулевой вклад, а оставшиеся gates — оставаться корректными (не «доставать» массу из несуществующего входа). Показать это формулой и покрыть тестом.

### A7. Выбрать fusion levels

Сравнить:

1. Stage 4 only.
2. Stages 3-4.
3. Stages 2-4.
4. Dense maps в stages 2-3, text только stage 4/readout.

Для каждого указать tensor shapes и дополнительную стоимость.

### A8. Descriptor readout

Сравнить:

- GAP stage 4;
- GGeM;
- attention pooling;
- residual addition fused descriptor к RGB descriptor.

Primary readout обязан сохранять прямой RGB information path.

### A9. Diagnostics

Реализовать минимум:

- mean/std gate по modality и stage;
- contribution norm `||a_m * Delta_m|| / ||X_rgb||`;
- cosine RGB vs fused descriptor;
- fraction saturated gates `<0.05` или `>0.95`;
- descriptor variance.

### A10. Tests

Обязательные тесты:

1. Output shape `[B,1024]` для B=1 и B=4.
2. Descriptor norm.
3. Identity behaviour при zero auxiliary residual.
4. Invalid-mask handling.
5. Satellite и UAV geometry projectors не смешиваются.
6. No NaN на constant segmentation/depth/CHM.
7. Backprop gradient достигает каждого active projector.

### A11. Персональные ablations

| ID | Сравнение |
|---|---|
| A-AB1 | static weights vs condition-aware |
| A-AB2 | content-only vs content+quality |
| A-AB3 | scalar vs channel gates |
| A-AB4 | independent sigmoid vs normalized softmax gates |
| A-AB5 | standard init vs identity-preserving init |
| A-AB6 | stage 4 vs stages 3-4 |
| A-AB7 | shared vs view-specific controller head |
| A-AB8 | GAP vs GGeM vs attention pooling |

### A12. Falsification

Гипотеза condition-aware controller считается не подтверждённой, если выполняется любое:

- static residual не хуже primary в пределах шума;
- gates почти постоянны по samples;
- один gate насыщен для большинства samples без contribution gain;
- улучшение есть только на одном seed;
- compute существенно растёт без R@1 gain;
- fused descriptor почти идентичен RGB при заявленном multimodal effect.

## 6. Кодовые артефакты

Ожидаемые файлы:

```text
src/fuse_proj/models/fusion/base.py
src/fuse_proj/models/fusion/registry.py
src/fuse_proj/models/fusion/condition_aware.py
in/config_files/fusion_condition_aware.gin
tests/test_condition_aware.py
reports/pavlenko/DESIGN.md
reports/pavlenko/IMPLEMENTATION_AND_RESULTS.md
```

## 7. Definition of Done

- [ ] Общий API принят всей командой.
- [ ] Evidence matrix заполнена.
- [ ] Три кандидата сравнены.
- [ ] Primary и fallback выбраны до full run.
- [ ] Satellite и UAV tensor flow полностью описаны.
- [ ] Gates математически определены.
- [ ] Реализованы diagnostics.
- [ ] Все tests проходят.
- [ ] Проведены A-AB1..A-AB8 для выбранного набора.
- [ ] Мороз выполнил code review.
- [ ] Результаты занесены в общий experiment registry.