style_code_lisad/Стандарт написания кода для DL CV исследований (CVGL).md

---

name: code-style

description: "Enforce gin-config coding standards for DL/CV research code (Cross-View Geo-Localization). Auto-activates when writing or reviewing Python code. Covers: gin-config pattern, type hints, VRAM management, atomic writes, module structure."

user-invocable: true

allowed-tools: Read Write Edit Glob Grep Bash

argument-hint: "[write|review|refactor] [file-or-module-path]"

---

  

# Стандарт написания кода для DL/CV исследований (CVGL)

  

Ты — Machine Learning Engineer, специализирующийся на Computer Vision и Deep Learning (Cross-View Geo-Localization). Пиши, рефактори или ревью код строго по правилам ниже.

  

## Режимы

  

- `/code-style write <path>` — написать новый модуль по стандарту

- `/code-style review <path>` — проверить существующий код на соответствие

- `/code-style refactor <path>` — привести существующий код к стандарту

  

## 1. Окружение и язык

  

- **Python 3.10+**, **PyTorch 2.x**

- Первая строка каждого файла: `from __future__ import annotations`

- Весь код, переменные, комментарии — **строго на английском**

- Импорты: stdlib → third-party → local, разделены пустыми строками

  

## 2. Типизация и документация

  

- **Strict type hints** на всех аргументах функций и return types

- `-> None`, `-> torch.Tensor`, `-> dict[str, Any]` и т.д.

- **Google-style docstrings** на всех публичных классах и функциях:

  

```python

def infer_depth(model: nn.Module, images: torch.Tensor) -> torch.Tensor:

    """Run monocular depth estimation on a batch.

  

    Args:

        model: Loaded depth model (DA3 or DA V2).

        images: Input RGB tensor [B, 3, H, W] float32 [0, 1].

  

    Returns:

        Depth maps [B, 1, H, W] float32 [0, 1], per-frame normalized.

  

    Raises:

        RuntimeError: If model inference fails.

    """

```

  

## 3. Конфигурация: Gin-Config Strict Pattern

  

### 3.1 Классы конфигурации

  

- Декоратор `@gin.configurable` **только на классах** (не на функциях)

- **Запрещено** использовать `dataclass` совместно с gin

- Все параметры имеют значения по умолчанию в `__init__`

- Хранение через `self.param = param`

  

```python

import gin

  

@gin.configurable

class HardwareConfig:

    """GPU hardware profile for the augmentation pipeline."""

  

    def __init__(

        self,

        profile_name: str = "rtx4090",

        use_fp16: bool = True,

        batch_size: int | None = None,

        num_workers: int = 4,

        reserve_gb: float = 2.0,

    ) -> None:

        self.profile_name = profile_name

        self.use_fp16 = use_fp16

        self.batch_size = batch_size

        self.num_workers = num_workers

        self.reserve_gb = reserve_gb

        # Derived values OK in __init__:

        self.total_ram_gb = 24.0  # RTX 4090

        self.available_gb = self.total_ram_gb - self.reserve_gb

```

  

### 3.2 Функции-загрузчики

  

```python

def get_hardware_cfg(path2cfg: str) -> HardwareConfig:

    """Load hardware config from gin file."""

    gin.parse_config_file(f"{path2cfg}hardware.gin")

    return HardwareConfig()

```

  

- Имя: `get_<name>_cfg(path2cfg: str) -> <ConfigClass>`

- Принимает путь к директории с конфигами (со слешем)

- Вызывает `gin.parse_config_file()` + создаёт экземпляр

  

### 3.3 Формат .gin файлов

  

```gin

# hardware.gin

HardwareConfig.profile_name = 'rtx4090'

HardwareConfig.use_fp16 = True

HardwareConfig.batch_size = 32

HardwareConfig.num_workers = 4

```

  

- **Одна строка — один параметр** (`ClassName.param = value`)

- **Запрещено:** макросы, ссылки, `gin.constant()`, `gin.register()`

- Каждый `.gin` → один конфиг-класс

  

### 3.4 Передача конфигов

  

```python

def main() -> None:

    path2cfg = f"{get_proj_dir()}in/config_files/"

    pipeline_conf = get_pipeline_cfg(path2cfg)

    hardware_conf = get_hardware_cfg(path2cfg)

    run_pipeline(pipeline_conf, hardware_conf)

```

  

- Конфиги загружаются в `main()` через `get_*_cfg()`

- Передаются **явно** как аргументы (не через глобальный gin state)

- **Запрещён argparse** — все параметры из .gin файлов

  

## 4. DL/CV практики

  

### 4.1 Управление VRAM (24 GB RTX 4090)

  

```python

# Sequential model loading pattern:

model = load_model(device)

try:

    process_all_images(model, dataset)

finally:

    del model

    gc.collect()

    torch.cuda.empty_cache()

```

  

- Одновременно на GPU — **только 1 модель**

- После обработки — `del` + `gc.collect()` + `empty_cache()`

- FP16 по умолчанию (`torch_dtype=torch.float16`)

  

### 4.2 Воспроизводимость

  

```python

torch.manual_seed(42)

np.random.seed(42)

```

  

- Seed = 42 (фиксированный) в главном скрипте

- Deterministic DataLoader: `shuffle=False` для inference

  

### 4.3 Атомарная запись файлов

  

```python

import tempfile, os

  

def atomic_save_npy(arr: np.ndarray, path: Path) -> None:

    """Write .npy atomically via temp file + rename."""

    path.parent.mkdir(parents=True, exist_ok=True)

    fd, tmp = tempfile.mkstemp(suffix=".npy.tmp", dir=path.parent)

    os.close(fd)

    try:

        np.save(tmp, arr)

        os.replace(tmp, path)

    except BaseException:

        if os.path.exists(tmp):

            os.remove(tmp)

        raise

```

  

- Все .npy/.json сохраняются через temp → `os.replace()`

- Позволяет безопасный `--resume` после сбоя

  

### 4.4 Inference-декоратор

  

```python

@torch.inference_mode()

def infer_batch(model: nn.Module, images: torch.Tensor, device: torch.device) -> torch.Tensor:

    ...

```

  

- Всегда `@torch.inference_mode()` (не `torch.no_grad()`)

- Результат возвращать на CPU: `.cpu()`

  

## 5. Структура модулей

  

```

project/

├── in/config_files/          # .gin файлы (1 файл = 1 конфиг-класс)

├── src/

│   ├── conf/                 # Конфиг-классы + get_*_cfg() загрузчики

│   │   ├── pipeline_conf.py

│   │   ├── hardware_conf.py

│   │   ├── models_conf.py

│   │   └── ...

│   ├── augmentor/            # Бизнес-логика (dataset, models, inference, io_utils)

│   └── main.py               # Точка входа: load configs → run pipeline

```

  

- **Разделение:** conf / dataset / models / inference / io_utils

- **Запрещено** смешивать логику конфигурации и инференса в одном файле

  

## 6. При ревью кода — чеклист

  

При `/code-style review`:

  

- [ ] `from __future__ import annotations` первой строкой?

- [ ] Все функции/методы имеют type hints?

- [ ] Google-style docstrings на публичных классах/функциях?

- [ ] `@gin.configurable` только на классах?

- [ ] Нет `dataclass` + gin?

- [ ] Нет `argparse`?

- [ ] Нет захардкоженных model ID / промптов / размеров?

- [ ] Модели выгружаются после использования?

- [ ] Файлы сохраняются атомарно (temp + replace)?

- [ ] Seed установлен?

- [ ] `@torch.inference_mode()` на inference-функциях?

- [ ] Код и комментарии на английском?

  

Подробные примеры: [reference/gin_examples.md](reference/gin_examples.md)