style_code_lisad/code-style/SKILL.md

name, description, user-invocable, allowed-tools, argument-hint

name	description	user-invocable	allowed-tools	argument-hint
code-style	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.	true	Read Write Edit Glob Grep Bash	[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 на всех публичных классах и функциях:

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

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 Функции-загрузчики

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 файлов

# 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 Передача конфигов

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)

# 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 Воспроизводимость

torch.manual_seed(42)
np.random.seed(42)

• Seed = 42 (фиксированный) в главном скрипте
• Deterministic DataLoader: shuffle=False для inference

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

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-декоратор

@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