# 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 的地方")