docs/standards.md

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 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.