# MODELING DOMAIN KNOWLEDGE BASE

## OVERVIEW
`opengait/modeling/` defines model contracts and algorithm implementations: `BaseModel`, loss aggregation, backbones, concrete model classes.

## STRUCTURE
```text
opengait/modeling/
├── base_model.py        # canonical train/test lifecycle
├── loss_aggregator.py   # training_feat -> weighted summed loss
├── modules.py           # shared NN building blocks
├── backbones/           # backbone registry + implementations
├── losses/              # loss registry + implementations
└── models/              # concrete methods (Baseline, ScoNet, DeepGaitV2, ...)
```

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Add new model | `models/*.py` + `docs/4.how_to_create_your_model.md` | must inherit `BaseModel` |
| Add new loss | `losses/*.py` | expose via dynamic registry |
| Change training lifecycle | `base_model.py` | affects every model |
| Debug feature/loss key mismatches | `loss_aggregator.py` | checks `training_feat` keys vs `loss_cfg.log_prefix` |

## CONVENTIONS
- `forward()` output contract is fixed dict with keys: `training_feat`, `visual_summary`, `inference_feat`.
- `training_feat` subkeys must align with configured `loss_cfg[*].log_prefix`.
- Backbones/losses/models are discovered dynamically via package `__init__.py`; filenames matter operationally.

## ANTI-PATTERNS
- Do not return arbitrary forward outputs; `LossAggregator` and evaluator assume fixed contract.
- Do not put model classes outside `models/`; config lookup by `getattr(models, name)` depends on registry.
- Do not ignore DDP loss wrapping (`get_ddp_module`) in loss construction.