| # BLUX-cA Repository Standards | |
| This document summarizes the house style used across `ca.py`, `ca/cli.py`, and related modules. New code should align with these conventions. | |
| ## CLI Conventions | |
| - Use [Typer](https://typer.tiangolo.com/) for subcommands. Group related commands via `typer.Typer` and attach with `add_typer`. | |
| - Default output is concise and human-readable. Prefer Rich tables or `console.print_json` when structured output is needed. | |
| - Non-zero exit codes signal user-facing errors; raise `typer.Exit(code=1)` or `SystemExit(1)` after printing a clear message. | |
| - Provide `--help` for every command and avoid hidden flags. Respect environment overrides such as `DATASET_DIR`, `BASE_MODEL`, and `RUN_NAME` when present. | |
| ## Logging and Output | |
| - Rely on lightweight logging: Rich console output for user-facing flows; `print` only for simple scripts. Avoid noisy debug logs unless explicitly requested. | |
| - For background helpers, prefer the standard `logging` module with INFO defaults and DEBUG gated by env flags. | |
| ## Configuration | |
| - Store defaults in versioned YAML (e.g., `train/configs/`). | |
| - Precedence: environment variables > CLI flags > config file defaults. | |
| - Validate configuration early and fail fast with actionable error text. | |
| ## Error Handling | |
| - Catch expected user errors (missing paths, invalid config) and present actionable messages before exiting non-zero. | |
| - Let unexpected exceptions propagate to aid debugging during development. | |
| ## Paths and Filesystem | |
| - Use `pathlib.Path` for all filesystem interactions and support execution from any working directory. | |
| - Resolve repo-relative paths via `Path(__file__).resolve()` parents when needed instead of relying on CWD. | |
| - Write generated artifacts to `runs/` (gitignored) and avoid committing binaries or checkpoints. | |
| ## Code Style | |
| - Target Python 3.10+ with type hints on public functions and return types. | |
| - Keep functions small and focused. Include brief module and function docstrings describing intent and behavior. | |
| - Follow `black` formatting and `ruff` lint rules defined in `pyproject.toml`. | |
| ## Testing and Tooling | |
| - Provide `python -m compileall`-clean code for scripts. | |
| - Add smoke checks for CLI entrypoints (`blux-ca --help`, doctor checks, training `--help`). | |
| - Use pytest for automated tests; keep smoke tests fast and GPU-optional. | |