davyleroy/malaria-smear-classifier

Offline AI second-reader for malaria blood-smear microscopy. Segments red blood cells, extracts features, and flags P. falciparum with an interpretable logistic-regression model. Sensitivity-first, human-in-the-loop, built for low-resource health centres in Nigeria. # MalariaScope — offline AI second reader for malaria microscopy Offline decision support for malaria blood-smear microscopy. Segments red blood cells from a field-of-view image, extracts named features, and flags suspected *P. falciparum* with an interpretable logistic-regression model. Sensitivity-first, human-in-the-loop, built for health-centre laboratories in Nigeria. > **Decision support only. Confirm by microscopy. A negative does not rule out > malaria in a symptomatic patient.** The tool never finalises a diagnosis. Every flag is confirmed by a human under the microscope. See `docs/PRD_MalariaScope.md` for the full product requirements, scope boundaries, and non-goals. --- ## Quickstart Requires **Python 3.11** (3.10–3.12 supported; 3.13+ lacks reliable wheels for the imaging stack) and about **2 GB of free disk** for the datasets. ```bash make setup # create .venv and install pinned dependencies make data # download NIH + Bowen datasets (the ONLY network step) make split # build the patient-level split and run the leakage gate make train # fit the model, select the threshold, write reports/metrics.json make quiz # requirement-by-requirement PASS/FAIL scorecard make app-streamlit ``` `make help` lists every target. --- ## What runs offline Everything except `make data` and `make wheelhouse`. No component under `src/malariascope/` makes a network call, and `scripts/verify_offline.py` proves it by shutting sockets and running a full inference: ```bash make offline ``` For an air-gapped machine, build a wheelhouse on a connected machine and carry it across with the repository: ```bash make wheelhouse # populates vendor/ make install-offline # pip install --no-index --find-links vendor ``` --- ## Repository layout | Path | Contents | |---|---| | `src/malariascope/` | The pipeline. Stages 1–6, plus config, splitting, and messages. | | `apps/` | Two interchangeable UIs over one shared inference core. | | `script …