buwituze/Africa-deep-tech-hackathon

# 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 pip install "git+github.com" ``` ### 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 The profiler runs in two primary modes: ### 1. Participant Mode (Local Self-Check) Used by participants to smoke-test their submission locally. It runs the throughput bench and resource sampling, but skips accuracy evaluations. ```bash adtc-profiler run \ --submission /path/to/your-submission-repo \ --mode participant \ --output submission.json \ --skip-accuracy ``` ### 2. Audit Mode (Evaluation Sandbox) Used by the ADTC evaluation orchestrator inside secure cloud VMs. ```bash adtc-profiler run \ --submission /path/to/your-submission-repo \ --mode audit \ --output audit.json ``` --- ## ⚖️ Comparing Reports After running both the local self-check and the audit evaluations, you can compare the output JSON files to check if they conform to the competition's variance tolerances: ```bash adtc-profiler compare submission.json audit.json --output verdict.json ``` ### Tolerance Guidelines To ensure fairness across differing environments, the comparison engine tolerates minor variances: | Metric | Tolerance | Status | | :--- | :--- | :--- | | `memory.peak_rss_mb` | ±15% | Flags if exceeded; fails if >50% | | `memory.steady_state_rss_mb` | ±15% | Flags if exceeded; fails if >50% | | `throughput.tokens_per_second_genera …