# AGENTS.md

## Проект

Задача проекта: объединить RGB, text, segmentation и geometry для cross-view geo-localization на GTA-UAV-LR с backbone StripNet-small.

## Инварианты

- Документация и отчёты пишутся на русском языке.
- Код, имена сущностей, type hints, docstrings и комментарии пишутся на английском языке.
- Python 3.10+, PyTorch 2.x, gin-config.
- Первая строка каждого Python-файла: `from __future__ import annotations`.
- Все публичные функции и классы имеют type hints и Google-style docstrings.
- Конфигурация экспериментов хранится в `in/config_files/`; не добавлять `argparse`.
- В коде не хардкодить пути к GTA-UAV, весам и output directories.
- Все экспериментальные записи должны содержать config snapshot, git commit, seed и метрики.
- Все тензорные преобразования в fusion-модулях документируются формами.
- Сравнения оформляются таблицами.

## Архитектурный контракт

- Backbone: shared StripNet-small.
- Stage channels: `[64, 128, 320, 512]`.
- Stage maps при входе 256: `[64x64, 32x32, 16x16, 8x8]`.
- Satellite geometry: CHM.
- UAV geometry: relative depth.
- Segmentation: 17 unified classes.
- Output каждой view-ветки: L2-нормированный descriptor `[B, 1024]`.
- Satellite и UAV кодируются независимо.
- Cross-view взаимодействие внутри encoder запрещено.

## Совместная работа

- Общие интерфейсы меняются только через совместное решение всех трёх сотрудников.
- Каждый fusion-вариант реализует общий API из `src/fuse_proj/models/fusion/base.py`.
- Feature branches:
  - `feature/pavlenko-condition-aware`
  - `feature/blizno-token-bottleneck`
  - `feature/moroz-role-aware`
  - `integration/fusion-benchmark`
- Обязательные взаимные ревью:
  - Павленко ревьюит код Близно.
  - Близно ревьюит код Мороза.
  - Мороз ревьюит код Павленко.
- Нельзя создавать отдельный dataloader, loss или eval protocol для одного варианта без согласованного общего изменения.

## Документация

- Контекст системы: `docs/00_project/06_MERIDIAN_CONTEXT.md`.
- Канонические reference-документы ведутся цепочками версий: полная база в `docs/02_references/**/_version_chain/`, актуальная дельта в корне тематической папки. Читать цепочкой; при противоречии прав более поздний документ.

## Переиспользование

- `vendor_reference/` является read-only снимком.
- Источники переиспользуемого кода указаны в `docs/00_project/05_REPOSITORY_REUSE_GUIDE.md`.
- При переносе кода сохранять происхождение в module docstring.
- Не копировать датасет, веса и run outputs в git.

## Проверка перед merge

1. Unit tests проходят.
2. Shape tests проходят для batch sizes 1 и 4.
3. Выход finite и имеет форму `[B, 1024]`.
4. Норма descriptor близка к 1.
5. Satellite и UAV forward работают независимо.
6. Gin config сохраняется вместе с run.
7. Smoke run выполняется на малом subset.
8. Нет незадокументированных изменений общего protocol.