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-studio/opengait_studio 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:

uv sync

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):

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):

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:

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:

uv run python -m opengait_studio --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:

sh misc/clean_process.sh

Test Commands (especially single test)

Run all tests:

uv run pytest tests

Run one file:

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

Run one test function:

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

Run by keyword:

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

Lint / Typecheck

Typecheck with basedpyright:

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