OpenGait/AGENTS.md

# OpenGait Agent Guide

This file is for autonomous coding agents working in this repository.
Use it as the default playbook for commands, conventions, and safety checks.

## Scope and Ground Truth

- Repository: `OpenGait`
- Runtime package: `opengait/`
- Primary entrypoint: `opengait/main.py`
- Package/runtime tool: `uv`

Critical source-of-truth rule:
- `opengait/demo` is an implementation layer and may contain project-specific behavior.
- When asked to “refer to the paper” or verify methodology, use the paper and official citations as ground truth.
- Do not treat demo/runtime behavior as proof of paper method unless explicitly cited by the paper.

## Environment Setup

Install dependencies with uv:

```bash
uv sync --extra torch
```

Notes from `pyproject.toml`:
- Python requirement: `>=3.10`
- Dev tooling includes `pytest` and `basedpyright`
- Optional extras include `torch` and `parquet`

## Build / Run Commands

Train (DDP):

```bash
CUDA_VISIBLE_DEVICES=0,1 uv run python -m torch.distributed.launch \
  --nproc_per_node=2 opengait/main.py \
  --cfgs ./configs/baseline/baseline.yaml --phase train
```

Test (DDP):

```bash
CUDA_VISIBLE_DEVICES=0,1 uv run python -m torch.distributed.launch \
  --nproc_per_node=2 opengait/main.py \
  --cfgs ./configs/baseline/baseline.yaml --phase test
```

Single-GPU eval example:

```bash
CUDA_VISIBLE_DEVICES=0 uv run python -m torch.distributed.launch \
  --nproc_per_node=1 opengait/main.py \
  --cfgs ./configs/sconet/sconet_scoliosis1k_local_eval_1gpu.yaml --phase test
```

Demo CLI entry:

```bash
uv run python -m opengait.demo --help
```

## DDP Constraints (Important)

- `--nproc_per_node` must match visible GPU count in `CUDA_VISIBLE_DEVICES`.
- Test/evaluator sampling settings are strict and can fail if world size mismatches config.
- If interrupted DDP leaves stale processes:

```bash
sh misc/clean_process.sh
```

## Test Commands (especially single test)

Run all tests:

```bash
uv run pytest tests
```

Run one file:

```bash
uv run pytest tests/demo/test_pipeline.py -v
```

Run one test function:

```bash
uv run pytest tests/demo/test_pipeline.py::test_resolve_stride_modes -v
```

Run by keyword:

```bash
uv run pytest tests/demo/test_window.py -k "stride" -v
```

## Lint / Typecheck

Typecheck with basedpyright:

```bash
uv run basedpyright opengait tests
```

Project currently has no enforced formatter config in root tool files.
Follow existing local formatting and keep edits minimal.

## High-Value Paths

- `opengait/main.py` — runtime bootstrap
- `opengait/modeling/base_model.py` — model lifecycle contract
- `opengait/modeling/models/` — model zoo implementations
- `opengait/data/dataset.py` — dataset loading rules
- `opengait/data/collate_fn.py` — frame sampling behavior
- `opengait/evaluation/evaluator.py` — evaluation dispatch
- `configs/` — experiment definitions
- `datasets/` — preprocessing and partitions

## Code Style Guidelines

### Imports
- Keep ordering consistent: stdlib, third-party, local.
- Prefer explicit imports; avoid wildcard imports.
- Avoid introducing heavy imports in hot paths unless needed.

### Formatting
- Match surrounding file style (spacing, wrapping, structure).
- Avoid unrelated formatting churn.
- Keep diffs surgical.

### Types
- Add type annotations for new public APIs and non-trivial helpers.
- Reuse established typing style: `typing`, `numpy.typing`, `jaxtyping` where already used.
- Do not suppress type safety with blanket casts; keep unavoidable casts narrow.

### Naming
- `snake_case` for functions/variables
- `PascalCase` for classes
- `UPPER_SNAKE_CASE` for constants
- Preserve existing config key names and schema conventions

### Error Handling
- Raise explicit, actionable errors on invalid inputs.
- Fail fast for missing files, bad args, invalid shapes, and runtime preconditions.
- Never swallow exceptions silently.
- Preserve CLI error semantics (clear messages, non-zero exits).

### Logging
- Use module-level logger pattern already in codebase.
- Keep logs concise and operational.
- Avoid excessive per-frame logging in realtime/demo loops.

## Model and Config Contracts

- New models should conform to `BaseModel` expectations.
- Respect forward output dictionary contract used by loss/evaluator pipeline.
- Keep model registration/discovery patterns consistent with current package layout.
- Respect sampler semantics from config (`fixed_unordered`, `all_ordered`, etc.).

## Data Contracts

- Runtime data expects preprocessed `.pkl` sequence files.
- Partition JSON files are required for train/test split behavior.
- Do not mix modalities accidentally (silhouette / pose / pointcloud) across pipelines.

## Research-Verification Policy

When answering methodology questions:
- Prefer primary sources (paper PDF, official project docs, official code tied to publication).
- Quote/cite paper statements when concluding method behavior.
- If local implementation differs from paper, state divergence explicitly.
- For this repo specifically, remember: `opengait/demo` may differ from paper intent.

## Cursor / Copilot Rules Check

Checked these paths:
- `.cursor/rules/`
- `.cursorrules`
- `.github/copilot-instructions.md`

Current status: no Cursor/Copilot instruction files found.

## Agent Checklist Before Finishing

- Commands executed with `uv run ...` where applicable
- Targeted tests for changed files pass
- Typecheck is clean for modified code
- Behavior/documentation updated together for user-facing changes
- Paper-vs-implementation claims clearly separated when relevant