Africa-Deep-Tech-Foundation/adtc-profiler

# ADTC Profiler Reference profiler CLI for the **Africa Deep Tech Challenge (ADTC) 2026** Laptop LLM track. The tool measures local GGUF models running through `llama.cpp` and emits schema-valid JSON benchmark reports capturing throughput, memory footprint, CPU utilization, thermals, and optional accuracy metrics. --- ## 📥 Installation Install the profiler directly from GitHub using `pip` or `uv`: ```bash python3 -m pip install "git+github.com" ``` > Use `python3 -m pip` (or `pip3`) — macOS and most Linux distros do not ship a bare `pip` command. The default install includes the full accuracy benchmark stack (lm-eval + llama-cpp-python), so one install produces complete, scoreable reports. Note that `llama-cpp-python` compiles from source on most platforms — you need a C/C++ toolchain (Xcode Command Line Tools on macOS, `build-essential` on Ubuntu) and the install can take a few minutes. ### System Prerequisites To profile model executions correctly, the tool relies on native binaries: 1. **`llama-bench`**: Must be installed and available on your system `PATH`. This is part of the `llama.cpp` toolset. 2. **Python >= 3.11** --- ## 🧪 Usage A complete working example submission (metadata + model download script) lives in `examples/demo-submission/` — copy it to get started. The profiler runs in two primary modes: ### 1. Participant Mode (Gate 1) Run on your own laptop to produce the `submission.json` you ship. The full run includes the accuracy benchmark (accuracy is 50% of your score): ```bash adtc-profiler run \ --submission /path/to/your-submission-repo \ --mode participant \ --output submission.json ``` While iterating, add `--skip-accuracy` to skip the accuracy stage for a faster smoke-test loop — but your final submitted report should come from a full run. ### 2. Audit Mode (Evaluation Sandbox) Used by the ADTC evaluation orchestrator inside secure cloud VMs. ```bash adtc-profiler run \ --sub …