mutentman/pneumonia-detection-deep-cnn

Purpose and Entry Points

This repository trains and serves a TensorFlow/Keras CNN for binary pneumonia detection from chest X-ray images. Training starts at src/train.py; model architecture and image-pipeline logic are separated into src/model.py and src/dataset.py. User-facing inference entry points appear to be streamlit_app.py and src/app.py, with an HTML template at templates/index.html.

Dataset Ingestion and Augmentation

src/dataset.py owns loading the Kaggle Chest X-Ray Images (Pneumonia) dataset and constructing image generators. The expected external dataset boundary is local, untracked image data under data/raw/chest_xray/{train,test,val}. Training-time augmentation is used to improve robustness and mitigate class imbalance before batches reach the network.

Paths: src/dataset.py, src/train.py

CNN Model Definition

src/model.py defines the core 11-layer sequential CNN. The architecture uses convolutional layers with batch normalization and dropout, producing a binary pneumonia/non-pneumonia prediction. This module should remain independent of dataset paths and UI concerns so training and inference can load the same model definition or serialized artifact.

Paths: src/model.py, saved_models/best_model.keras

Training, Validation, and Model Selection

src/train.py is the orchestration boundary: it obtains data generators, builds/compiles the model, executes fitting, validates performance, and evaluates the held-out test split. Early stopping and checkpointing select the best validation-stage model rather than relying only on the final epoch. Training produces history artifacts such as loss/accuracy plots and persists the selected Keras model.

Paths: src/train.py, src/dataset.py, saved_models/best_model.keras

Persisted Model Boundary

The trained model is serialized as a Keras artifact and consumed separately from training. saved_models/best_model.keras is the current packaged inference asset. In normal development, model artifacts are generated from the external dataset and should be treated as versioned runtime inputs to serving applications, not source code.

Paths: saved_models/best_model.keras, src/train.py

Inference and Presentation Layer

The repository contains two likely serving surfaces: a Streamlit interface in streamlit_app.py and an application module in src/app.py; the latter is associated with templates/index.html, suggesting a server-rendered upload/inference interface. These layers should load the persisted Keras model, preprocess a user-supplied X-ray consistently with the training pipeline, run prediction, and present the classification result. They are downstream of, and should not trigger, training.

Paths: streamlit_app.py, src/app.py, templates/index.html

Runtime and External Dependencies

Python is the runtime (runtime.txt), with dependencies declared in requirements.txt. Material external dependencies are TensorFlow/Keras for CNN training/inference, the Kaggle-hosted chest-X-ray dataset for model development, and the local filesystem for raw images and saved model artifacts. No database, queue, or cloud service is indicated by the repository tree.

Paths: requirements.txt, runtime.txt, README.md