style_code_lisad/Переход от `argparse` и `dataclass` к `gin-config`.md

Отличная инициатива. Переход от `argparse` и `dataclass` к `gin-config` в научно-исследовательских проектах по глубокому обучению — это мощный шаг, который сильно упрощает управление гиперпараметрами и версионирование экспериментов.

Ваш подход в `REQUIREMENTS_GIN_STYLE.md`, где вы используете `gin` для конфигурации классов, но **явно передаете объекты конфигов** (избегая глобального состояния `gin`), — это лучшая практика, которая решает главную проблему этого фреймворка.

Ниже представлены разработанный **SKILL (набор правил)**, **Prompt-шаблон** для ИИ, а также **сравнение конфигураций** с финальными рекомендациями.

---

### 1. SKILL: Стандарт написания кода для DL/CV исследований (Cross-View Geo-Localization)

Этот свод правил объединяет ваши базовые требования со спецификой задачи кросс-вью геолокализации и выбранным стилем `gin-config`.

**Общие требования к Python-коду:**

- **Версии:** Python 3.10+, PyTorch 2.x.
    
- **Импорты:** Обязательно `from __future__ import annotations` первой строкой в каждом файле.
    
- **Язык:** Весь код, переменные и комментарии строго на **английском языке**.
    
- **Типизация (Type Hints):** Строгая типизация для всех аргументов функций и возвращаемых значений (`-> None`, `-> torch.Tensor` и т.д.).
    
- **Документация:** Docstrings в формате **Google-style** для всех публичных классов и функций.
    

**Архитектура и управление ресурсами (CV/DL специфика):**

- **Воспроизводимость:** Обязательная фиксация seed (`torch.manual_seed`, `np.random.seed`) в главном скрипте.
    
- **Управление VRAM:** Из-за ограничений в 24 GB VRAM (RTX 4090) модели должны загружаться последовательно (`sequential model loading`). После использования модель выгружается из памяти (`del model`, `gc.collect()`, `torch.cuda.empty_cache()`).
    
- **Отказоустойчивость:** Запись файлов (например, `.npy`) должна быть атомарной (сохранение во временный файл `tmp` с последующим `os.replace`), чтобы пайплайн мог безопасно возобновить работу (`--resume`) после сбоя.
    
- **Разделение логики:** Строгое разделение на `dataset` (загрузка данных), `models` (инициализация), `inference` (прогон батчей) и `io_utils` (сохранение).
    

**Конфигурация (Gin-Config Style):**

- **Инкапсуляция:** Конфигурация осуществляется через классы, декорированные `@gin.configurable`. Запрещено использовать `dataclass` совместно с gin.
    
- **Инициализация:** Все параметры должны иметь значения по умолчанию в методе `__init__` класса.
    
- **Формат .gin:** Плоский формат файлов (одна строка — один параметр `ClassName.param = value`). Запрещены сложные конструкции gin (макросы, ссылки, `gin.constant()`).
    
- **Логика загрузки:** Использование паттерна функций-загрузчиков `get_<name>_cfg(path2cfg)`, которые вызывают `gin.parse_config_file()` и возвращают экземпляр конфигурационного класса.
    
- **Явная передача:** Объекты конфигурации передаются в функции пайплайна явно через аргументы, использование глобального состояния gin для получения параметров внутри функций запрещено.
    

---

### 2. Prompt-шаблон для генерации кода (System Prompt)

Вы можете использовать этот промпт для постановки задач нейросети (например, при рефакторинге старого кода или написании новых модулей).

Markdown

```
You are an expert Machine Learning Engineer and Python Developer specializing in Computer Vision and Deep Learning (specifically Cross-View Geo-Localization). 
Your task is to write, refactor, or review Python code according to the strict guidelines defined below.

### THE SKILL (Coding Standards)

1. **Environment & Language**:
   - Target Python 3.10+ and PyTorch 2.x.
   - Start all files with `from __future__ import annotations`.
   - All code, variable names, and comments MUST be in English.
   
2. **Typing & Documentation**:
   - Use strict type hints for all function arguments and return types.
   - Use Google-style docstrings for all classes and functions.

3. **Configuration (Gin-Config Strict Pattern)**:
   - Use `gin-config` for managing hyperparameters. Do NOT use `argparse` or `dataclass`.
   - Apply `@gin.configurable` ONLY to classes, not functions.
   - Provide default values for all parameters inside the class `__init__` method. Store parameters as instance attributes (`self.param = param`).
   - Define dedicated loader functions named `get_<name>_cfg(path2cfg)` that call `gin.parse_config_file(gin_file)` and return the instantiated class object.
   - Configuration objects must be passed explicitly as arguments to functions/pipelines. Never rely on global gin state inside execution logic.

4. **Deep Learning / CV Best Practices**:
   - **VRAM Management**: Models must be explicitly loaded and unloaded (`del model`, `torch.cuda.empty_cache()`) when doing sequential multi-model processing to fit within 24GB VRAM limits.
   - **Reproducibility**: Ensure deterministic behavior (e.g., set seeds using `torch.manual_seed`, `np.random.seed`).
   - **Fault Tolerance**: Use atomic file writes (save to `.tmp` then `os.replace`) to allow safe resumption of interrupted pipelines.

### Task Description:
[INSERT YOUR SPECIFIC TASK HERE. Example: Refactor the provided `augment_dataset.py` script to remove argparse and integrate the Gin-Config Strict Pattern described above using the 5 config classes.]
```

---

### 3. Примеры конфигов и сравнение подходов

Для вашей задачи (автоматическое аннотирование датасета генераторами) нам нужно конфигурировать пути, параметры железа, идентификаторы моделей и настройки аугментации.

#### Вариант А: Обычный `argparse` + `dataclass` (То, что у вас было)

- **Плюсы:** Не требует сторонних библиотек, отлично подходит для простых скриптов.
    
- **Минусы:** Когда параметров становится больше 15-20 (как у вас в 5 классах), командная строка превращается в хаос (`python script.py --depth-model xyz --use-fp16 --batch-size 8 ...`). Сложно отслеживать, с какими параметрами был запущен эксперимент неделю назад.
    

#### Вариант Б: YAML + Hydra / OmegaConf

YAML

```
# hardware.yaml
profile_name: rtx4090
use_fp16: true
batch_size: 8
num_workers: 4
reserve_gb: 2.0
```

- **Плюсы:** Иерархическая структура, легко читается, де-факто стандарт индустрии для многих фреймворков.
    
- **Минусы:** Требует написания шаблонного кода для парсинга (чтение файла, конвертация словаря в `dataclass`). Если использовать Hydra, то она "захватывает" архитектуру приложения (требует декоратора `@hydra.main`), что усложняет дебаг.
    

#### Вариант В: Ваш плоский `gin-config` стиль

Code snippet

```
# hardware.gin
HardwareConfig.profile_name = 'rtx4090'
HardwareConfig.use_fp16 = True
HardwareConfig.batch_size = 8
HardwareConfig.num_workers = 4
HardwareConfig.reserve_gb = 2.0
```

Python

```
# Загрузка
@gin.configurable
class HardwareConfig:
    def __init__(self, profile_name='rtx4090', ...): ...

def get_hardware_cfg(path2cfg):
    gin.parse_config_file(f"{path2cfg}hardware.gin")
    return HardwareConfig()
```

- **Плюсы:** * **Нулевой бойлерплейт при парсинге:** Вы просто парсите файл, и gin автоматически подставляет значения в параметры `__init__` класса.
    
    - **Легкость логирования:** Сохранить весь конфиг эксперимента можно вызвав `gin.config_str()`.
        
    - **Защита от опечаток:** Если вы напишете в конфиге `HardwarConfig.batch = 8`, `gin` упадет с ошибкой еще до запуска тяжелых вычислений, потому что такого аргумента нет.
        
- **Минусы:**
    
    - Не поддерживает вложенные иерархии (сложно группировать очень сложные структуры, но для ваших 5 конфигов это не критично).
        
    - Многие используют `gin` как антипаттерн "глобального состояния" (когда функции по всему коду неявно тянут параметры из эфира).
        

### 📝 Финальная рекомендация

**Строго придерживайтесь вашего `REQUIREMENTS_GIN_STYLE.md`.** Вы выбрали идеальный компромисс: вы используете `gin-config` для того, в чем он силен (красивая и лаконичная привязка параметров текстового файла к аргументам класса без парсеров словарей), но при этом **запрещаете его главную слабость** — неявное глобальное состояние. Загрузив параметры в объект конфигурации (например, `hardware_conf = get_hardware_cfg(...)`), вы дальше передаете его в пайплайн явно. Это делает код тестируемым, читаемым и идеально подходящим для глубокого обучения.

Подсказать ли вам, как должен выглядеть итоговый рефакторинг `augment_dataset.py` с применением этих правил?