AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
- `app.py`: Gradio entrypoint orchestrating model initialization, audio preprocessing, and inference flow.
- `src/`: Supporting modules (`audio_analysis/` for wav2vec2 utilities, `vram_management/` for GPU-safe layers, `utils.py` helpers).
- `utils/`: Infrastructure helpers (`model_loader.py` for WAN/InfiniteTalk weights, `gpu_manager.py` for memory checks/cleanup).
- `wan/`: Upstream InfiniteTalk model code; treat as vendor code when updating.
- `assets/` and `examples/`: UI assets and sample media for quick demos; safe to extend.
- `requirements.txt`, `packages.txt`, `Dockerfile`: Deployment dependencies (note: PyTorch + flash-attn installed via Dockerfile/HF build, not from requirements).

## Setup, Build, and Local Run
- Create an isolated env: `python -m venv .venv && source .venv/bin/activate`.
- Install Python deps: `pip install -r requirements.txt` (PyTorch/flash-attn come from the base image or HuggingFace Space build).
- Launch UI locally: `python app.py` (Gradio on port 7860 by default).
- Quick sanity check: `python -m py_compile app.py` to catch syntax errors before pushing.
- Docker-based run (mirrors HF build): `docker build -t infinitetalk . && docker run -p 7860:7860 infinitetalk`.

## Coding Style & Naming Conventions
- Python 3.10+, PEP 8 with 4-space indentation; favor type hints where practical.
- Functions/variables: `snake_case`; classes: `PascalCase`; constants: `UPPER_SNAKE_CASE`.
- Prefer `logging` over `print` (consistent with existing modules); keep log level INFO for user-facing runs.
- Add concise docstrings for public functions; keep module-level comments minimal and purposeful.

## Testing Guidelines
- No automated test suite yet; aim to add `pytest`-style tests under `tests/` mirroring `src/` modules.
- Until then, validate with: (1) `python -m py_compile` for syntax, (2) short inference smoke test using `examples/` media at 480p/30–40 steps.
- When adding tests, name files `test_<module>.py` and target functional paths (audio preprocessing, GPU guardrails, model loader paths).

## Commit & Pull Request Guidelines
- Repository has no historical git log; use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`) for clarity.
- One topic per commit; keep messages imperative and ≤72 chars in the subject.
- PRs should include: brief summary of behavior change, commands run (tests or smoke steps), any new dependencies, and before/after screenshots or sample outputs if UI/inference is affected.
- Avoid committing large model weights or cached downloads; rely on `ModelManager` to fetch at runtime and .gitignore caches.

## Security & Configuration Tips
- For private models, set `HF_TOKEN` in the environment/Space secrets; do not hardcode secrets.
- Respect GPU limits in `gpu_manager.py` when adjusting defaults; keep ZeroGPU duration estimates in mind.
- Large files: keep under repo size limits; store extra assets in external storage or release artifacts.