Repository Guidelines

Project Structure & Module Organization

Core configuration lives under lb_runner/ (benchmark_config.py).
Runner code is under lb_runner/; controller under lb_controller/; app-layer API under lb_app/; UI under lb_ui/.
Reporting and post-processing live under lb_analytics/; shared utilities in lb_common/; provisioning helpers in lb_provisioner/.
Use the stable APIs from lb_runner.api, lb_controller.api, and lb_app.api instead of importing deep modules.
UI layering: lb_ui may import only lb_app.api (and lb_common.api when needed). Avoid any direct imports from lb_controller, lb_runner, lb_plugins, lb_analytics, or lb_provisioner.
Collectors sit in lb_runner/metric_collectors/ (PSUtil, CLI, perf, eBPF) and workload plugins in lb_plugins/plugins/ (stress-ng, dd, fio, hpl), each with base abstractions plus concrete implementations.
Tests are under tests/; sample usage is in example.py. Output artifacts are written to benchmark_results/, reports/, and data_exports/ (these may be absent until generated).

Create env and install: uv venv && uv pip install -e .; include dev tools with uv pip install -e ".[dev]".
Run all tests locally: uv run pytest tests/ (pytest is configured with strict markers and minimal output). To mirror the container flow, use ./run_tests.sh, which builds Dockerfile and executes tests inside the image.
Quick smoke run: uv run python example.py to execute the sample controller flow after dependencies are installed.

Python 3.13, formatted with Black (line length 88) and linted with Flake8; type checking is strict via MyPy (no untyped defs, no implicit Optional). Pydocstyle runs with D100/D104/D203/D213 ignored; keep concise docstrings for public APIs.
Use snake_case for functions/variables/modules, PascalCase for classes, and UPPER_SNAKE_CASE for constants. Prefer well-named dataclasses for configs and keep CLI/tool shelling confined to collectors/generators.
Logging policy: configure logging via lb_common.configure_logging() in entrypoints. lb_runner does not auto-configure logging; callers should opt in to keep LB_EVENT output on stdout clean.

Framework: pytest; tests live in tests/ with files test_*.py, classes Test*, functions test_*. Favor unit tests for collectors/generators with fake command outputs and small integration tests that exercise the controller.
Add coverage for new metrics, config validation, and error handling paths; when a test needs system tools, mark or skip so it is safe on CI/docker.

Keep commits focused and present-tense (e.g., Add Docker support, Fix pyproject discovery as seen in history). Include issue IDs when applicable.
For PRs, provide a short summary, how to reproduce/validate, and note any new dependencies or required privileges (perf/eBPF, stress-ng). Include logs or screenshots for report changes and mention impacts on output directories or config formats.

Some collectors require root or Linux-only tooling; avoid running perf/eBPF-heavy commands on shared hosts without approval. Prefer the Docker flow for consistent system dependencies and to isolate high-load generators.

If a worktree contains submodules, remove it with scripts/remove_worktree_with_submodules.sh /path/to/worktree (this deinitializes submodules first, then force-removes the worktree).