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.