cluster4npu/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• main.py: Application entry point.
• core/: Engine and logic
  • core/functions/: inference, device, and workflow orchestration
  • core/nodes/: node types and base classes
  • core/pipeline.py: pipeline analysis/validation
• ui/: PyQt5 UI (windows, dialogs, components)
• config/: settings and theme
• resources/: assets
• tests/ + root test_*.py: runnable test scripts

Build, Test, and Development Commands

• Environment: Python 3.9–3.11.
• Setup (uv): uv venv && . .venv/bin/activate (Windows: .venv\Scripts\activate), then uv pip install -e .
• Setup (pip): python -m venv .venv && activate && pip install -e .
• Run app: python main.py
• Run tests (examples):
  • python tests/test_integration.py
  • python tests/test_deploy.py
  • Many tests are direct scripts; run from repo root.

Coding Style & Naming Conventions

• Python, PEP 8, 4-space indents.
• Names: modules/functions snake_case, classes PascalCase, constants UPPER_SNAKE_CASE.
• Prefer type hints and docstrings for new/changed code.
• Separation: keep UI in ui/; business logic in core/; avoid mixing concerns.

Testing Guidelines

• Place runnable scripts under tests/ and name test_*.py.
• Follow TDD principles in CLAUDE.md (small, focused tests; Red → Green → Refactor).
• GUI tests: create a minimal QApplication as needed; keep long-running or hardware-dependent tests optional.
• Example pattern: if __name__ == "__main__": run_all_tests() to allow direct execution.

Commit & Pull Request Guidelines

• Small, atomic commits; all tests pass before commit.
• Message style: imperative mood; note change type e.g. [Structural] vs [Behavioral] per CLAUDE.md.
• PRs include: clear description, linked issue, test plan, and screenshots/GIFs for UI changes.
• Do not introduce unrelated refactors in feature/bugfix PRs.

Security & Configuration Tips

• Do not commit firmware (fw_*.bin) or model (.nef) files.
• Avoid hard-coded absolute paths; use project-relative paths and config in config/.
• Headless runs: set QT_QPA_PLATFORM=offscreen when needed.

Agent-Specific Instructions

• Scope: applies to entire repository tree.
• Make minimal, targeted patches; do not add dependencies without discussion.
• Prefer absolute imports from package root; keep edits consistent with existing structure and naming.

TOOL to use

• 你可以使用 「gemini -p "xxx"」來呼叫 gemini cli 這個工具做事情， gemini cli 的上下文 token 很大，你可以用它找專案裡的程式碼，上網查資料等。但禁止使用它修改或刪除檔案。以下是一個使用範例
• Bash(gemini -p "找出專案裡使用 xAI 的地方")