HyperParallel — AGENTS.md

Project Overview

HyperParallel is an easy-to-use, high-performance distributed parallel acceleration library for distributed model training, inference and reinforcement learning. It provides unified abstractions for DP, FSDP/HSDP, TP, EP, CP, PP, activation checkpoint/swap, and parameter/optimizer offload. Hybrid strategies combine freely.

Primary target hardware: Ascend NPU and Nvidia GPU. Primary framework: PyTorch.

---

HyperParallel-RL Entry

• For RL-owned code, tests, docs, or agent rules, start with .agent/rules/hyper-rl.md. It is the sole RL entry.
• RL rules do not apply to other HyperParallel modules. Handle a required main-project change separately under that module's rules.
• Use the RL architecture, feature navigation, and module map to locate boundaries, implementation/test traces, and ownership.
• RL unit tests live in tests/ut/rl/, system tests in hyper_parallel/rl/tests/st/, and shared recipes in tests/common/rl_st_cases.py. RL ST is run explicitly and is temporarily outside the main-project PR gate. Follow the repository testing rules as well.

---

Dev Commands

# Editable install (required so edits to this repo are what Python imports)
cd /path/to/hyper-parallel && pip install -e .

# Verify import path points at this checkout (not a stale worktree / site-packages copy)
python -c "import hyper_parallel, os; print(hyper_parallel.__file__)"

# Unit tests (no multi-card)
pytest -vs tests/ut

# Lint / commit / PR (GitCode fork workflow)
python3 .agent/skills/autogit/scripts/autogit.py check
python3 .agent/skills/autogit/scripts/autogit.py commit -m "feat: ..."
python3 .agent/skills/autogit/scripts/autogit.py pr

# AGENTS.md Skills/Agents table vs disk (also in: autogit check / autogit commit).
# Non-zero exit is blocking. Run it whenever the diff touches *.md.
# Check changed documentation links separately; this script only checks catalogs.
python3 .agent/scripts/check_agents_catalog.py

Distributed ST helpers: torchrun_case() via tests.common.distributed_launcher, or parallel_case (see .agent/rules/testing.md).

---

Env Gotchas / Do Not

• Editable must track this tree. If pip show hyper_parallel shows another path (e.g. a deleted .worktrees/...), re-run pip install -e . from repo root. Do not rely on PYTHONPATH alone.
• Torch-only. The platform/ abstraction layer (and with it the MindSpore backend) has been removed. Every module uses native Torch APIs (torch.distributed, torch.Tensor, autograd) directly; do not reintroduce Platform dispatch or MindSpore implementations anywhere.
• Collectives. Use torch.distributed directly, or the thin wrappers in hyper_parallel/core/context_parallel/utils.py and hyper_parallel/core/dtensor/_utils.py.
• Never invent Jenkins build numbers or force-push shared branches in agent workflows.
• Hard distributed rules (canonical): .agent/rules/project-overview.md + .agent/rules/distributed.md — do not restate long-form elsewhere; link instead.

---

Key Modules

Module	Location	Purpose
RL	hyper_parallel/rl/	Synchronous LLM RL runtime with Qwen3, GRPO and PPO
DTensor	core/dtensor/	Local shard + DeviceMesh + Placements; redistribution cache
Shard	core/shard/	custom_shard / YAML ops + parallel_*.py
Tensor parallel	core/tensor_parallel/	parallelize_module(), ParallelStyle, mesh context
FSDP / HSDP	core/fully_shard/	Param shard/unshard; HSDP under same tree (hsdp_*.py)
Pipeline	core/pipeline_parallel/	Torch-only stage schedule, micro-batch, P2P
Activation	core/activation_checkpoint/, core/activation_memory/	SAC + activation swap
Checkpoint	core/distributed_checkpoint/	Distributed save/load
Multicore	core/multicore/	Torch-only component with private SHMEM and native build
Collectives	collectives/cc.py	Process groups
Tests	tests/ut/, tests/torch/	UT + distributed ST

---

Coding Conventions

Full details: .agent/rules/code-style.md (global hard constraint).

• Apache 2.0 header on .py (lines 1–16); PEP 8 / ~120 cols; Google-style docstrings; type hints on public APIs
• Imports at module top; the platform-backend lazy-import exception no longer applies
• Load code-style.md before generate / edit / commit / review; auto-fix before proceeding

---

Testing

Full details: .agent/rules/testing.md. How-to for new UT: skill add-unit-test.

• Runner: pytest + @arg_mark (tests/common/mark_utils.py)
• Authoring: prefer unittest.TestCase where existing UT does (pytest still runs them)
• UT: tests/ut/ — no distributed setup
• ST: torchrun_case / parallel_case (multi-card) — launchers must not import torch / hyper_parallel (see testing.md § ST launcher import rule)

---

Key Implementation Notes

Canonical detail: .agent/rules/distributed.md. Review examples: .agent/skills/code-review/distributed-guidelines.md (not a second SoT).

Highest-risk reminders (see rules for full text):

1. DTensor — is_partial() is a method; reduce_partial before redistribute; YAML op registry; SkipDTensorDispatch in grad hooks
2. Memory — resize_(0) after free; null consumed grad; clear PP recv buffers per micro-batch; swap wait_load/offload
3. Streams — handle.wait() before reading async output; event sync across streams; sync after non_blocking=True

---

Git Workflow

• Conventional Commits (feat: / fix: / docs:), ~80-char subject, imperative (see .agent/rules/code-style.md § Commit Convention; code line width is ~120)
• Squash WIP before opening PR; use autogit for GitCode fork + upstream
• Keep exactly one commit per PR. Amend subsequent fixes into that commit. Back up before rewriting history and use --force-with-lease with the expected remote SHA when updating the PR's own source branch.
• Optional git hook: copy .agent/hooks/commit-msg → .git/hooks/commit-msg (rejects AI attribution trailers; autogit also checks)

---

Hooks (harness-specific)

Configured in .agent/settings.json (Claude Code–style PostToolUse matchers). Scripts under .agent/hooks/:

Hook	When	Purpose
enforce-code-style.sh	After Write/Edit	Style guard on edited files
check-op-yaml.sh	After Write/Edit	Op YAML ↔ impl pairing checks
commit-msg	git commit-msg (manual install)	Block AI attribution trailers

Target harness today: Claude Code–compatible agent settings consuming .agent/settings.json. Other IDEs may not run these hooks — treat autogit check / pre-commit / CI as the cross-tool fallback. Do not assume hooks fire outside that harness.

---

AI Agent Configuration (.agent/)

Layering: AGENTS.md = ambient law · rules/ = path-scoped constraints · skills/ = invocable workflows (SoT for procedures) · agents/ = thin personas / quick advisors (must not duplicate skill formulas).

Skills

Skill	Description	Usage
autogit	GitCode fork: commit, PR, status, squash, lint/test gates	/commit, /create-pr, /test, …
code-review	Full distributed review (stream/memory/DTensor/collectives)	/code-review
dist-op-analysis	Operator analysis → plan (human confirm)	called before dist-op-dev
dist-op-dev	Implement + test from confirmed plan	/dist-op-dev
gate-doctor	GitCode PR gate diagnose → autofix to green	门禁 / autofix / /retest
parallel-strategy-analyzer	DP/FSDP/TP/PP/EP/CP strategy + cost estimate	/parallel-strategy-analyzer
add-unit-test	How-to for tests/ut (procedures)	when adding UT / coverage
hf-model-integration	Integrate HF-native or HF-component custom models through model-owned adapters	model onboarding / functional bring-up
hf-model-precision-validation	Validate module parity and distributed numerical self-consistency	model numerical acceptance / diagnosis

Commands

Command	Description
/commit	autogit commit
/test	autogit test (pytest tests/ut)
/create-pr	autogit pr → upstream
/code-review	code-review skill (+ mandatory code-style.md)
/gen-commit-msg	Message only, no commit

Agents

Agent	Role
planner	Read-only multi-file implementation plan
code-verifier	5-phase verify: style/lint, tests, distributed semantics, report
simple-code-reviewer	Fast checklist only — not full /code-review
code-reviewer	Thin proxy → skills/code-review (full review)
dtensor-dev-expert	DTensor / layout / redistribute / op dispatch
tensor-dev-expert	parallelize_module / ParallelStyle / mesh
fsdp-dev-expert	FSDP/HSDP shard, grad reduce, memory lifecycle
pipeline-dev-expert	PP schedule, micro-batch, activation swap hooks
ep-dev-expert	Expert parallel / MoE routing
activation-dev	Activation recompute/swap + LlamaFactory ordering (details in activation-dev-guide.md)
llamafactory-hp	LlamaFactory integration surface (activation details → activation-dev)
parallel-strategy-analyzer	Thin proxy → skills/parallel-strategy-analyzer

Rules (auto-applied by path)

Rule	Scope
project-overview	Global — identity + hard-rule shortlist
code-style	Global
distributed	core/**, collectives/**, **/fully_shard/**
multi-platform-features	core/** — list/collection API contracts
testing	tests/**
unit-test	tests/ut/** — hard constraints; how-to → skill add-unit-test
hyper-rl	hyper_parallel/rl/**, RL docs and agent rules — sole RL entry; also consult it for migrated RL tests
distributed-op-dev / distributed-op-testing / test-assertion-style	Op impl & tests (scoped)