docs: complete documentation

README.md

@@ -7,34 +7,149 @@ sdk: docker
 app_port: 7860
 ---
 
-# 🧠 Parkinson's Motor Impairment Score API
+# Parkinson's Motor Impairment Score API
 
- **FastAPI** backend that evaluates patient drawings (wave and spiral patterns) to detect and quantify motor impairments associated with Parkinson's disease.
+This project is a **FastAPI** service that predicts Parkinson's-related motor impairment from patient drawing images.
 
-This service utilizes deep learning models (**VGG19** and **ResNet101**) automatically dynamically fetched from Hugging Face along with a custom OpenCV pre-processing pipeline to score severity precisely.
+It accepts two drawing styles:
+
+- **Wave drawings**
+- **Spiral drawings**
+
+Each image is preprocessed and passed into a deep learning model to produce:
+
+- a raw model logit
+- a sigmoid probability
+- a normalized motor impairment score from 0 to 100
+- a severity label
+- a human-readable description
+
+The project is designed for **local development**, **Docker deployment**, and **Hugging Face Spaces**.
+
+
+The service is intended to:
+
+1. receive an uploaded image
+2. preprocess it consistently
+3. run inference using a pretrained model
+4. return a structured prediction response
+
+---
+
+## Key Features
+
+### 1. FastAPI-based service
+
+The API uses FastAPI for fast request handling, automatic validation, and interactive documentation.
+
+### 2. Two prediction routes
+
+- Wave drawings use a **VGG19-based** model
+- Spiral drawings use a **ResNet101-based** model
+
+### 3. Startup model loading
+
+Both models are loaded during application startup so the first request is faster.
+
+### 4. Custom preprocessing pipeline
+
+The image pipeline reproduces the original training preprocessing using:
+
+- OpenCV
+- NumPy
+- Pillow
+
+### 5. Hugging Face model download
+
+The trained `.h5` models are downloaded from Hugging Face Hub when needed.
+
+### 6. CORS support
+
+The API is configured to accept cross-origin requests from browser-based clients.
+
+### 7. Docker-ready deployment
+
+The repository includes a Dockerfile for Hugging Face Spaces deployment.
 
 ---
 
-## 🚀 Features
-* **Lightning Fast:** Implements a FastAPI lifecycle manager to preload multi-hundred-megabyte machine learning models straight into RAM on server startup, ensuring 0-second prediction latency.
-* **Dual Classifiers:**
-  * **Wave Patterns:** Analyzed via a VGG19 backbone.
-  * **Spiral Patterns:** Analyzed via a ResNet101 backbone.
-* **Torch-less:** Fully replicates the original PyTorch training `torchvision` image transformation pipeline using strictly `numpy` and `cv2` for ultra-lightweight deployment.
+## Repository Structure
+
+- [main.py](main.py) - FastAPI application entry point and API routes
+- [services/predictor.py](services/predictor.py) - model loading, preprocessing, and prediction logic
+- [services/**init**.py](services/__init__.py) - package initializer
+- [requirements.txt](requirements.txt) - Python dependencies
+- [Dockerfile](Dockerfile) - container configuration for deployment
+- [.github/workflows/deploy.yml](.github/workflows/deploy.yml) - GitHub Actions workflow for deployment to Hugging Face
+- [test/](test/) - sample images for testing and experimentation
+
+---
+
+## How the API Works
+
+### Request flow
+
+1. A client uploads a drawing image using multipart form data
+2. The API validates that the file is an image
+3. The image is converted into a consistent tensor-like NumPy array
+4. The correct model is loaded if not already cached
+5. The model returns a raw logit
+6. The logit is converted to a sigmoid probability
+7. The result is normalized into a motor impairment score
+8. A severity label and description are returned
+
+### Preprocessing pipeline
+
+The preprocessing logic performs the following steps:
+
+1. load the image
+2. convert to grayscale
+3. apply Otsu thresholding with inversion
+4. resize to 224 × 224
+5. replicate grayscale into 3 channels
+6. apply normalization logic compatible with the training setup
+7. add a batch dimension
 
 ---
 
-## 🛠️ API Endpoints
+## API Endpoints
+
+### Health check
+
+**GET /**
+
+Returns a simple status response.
+
+Example response:
+
+```json
+{
+  "status": "ok",
+  "message": "Welcome to the Motor Impairment Score API"
+}
+```
+
+### Predict wave drawing
+
+**POST /predict/wave**
 
-### 1. `POST /predict/wave`
-Accepts a drawn "wave" pattern image overlay and calculates severity.
+Accepts a wave drawing image and returns a prediction.
 
-### 2. `POST /predict/spiral`
-Accepts a drawn "spiral" pattern image overlay and calculates severity.
+### Predict spiral drawing
 
-**Input Format:** `multipart/form-data` with an image file.
+**POST /predict/spiral**
+
+Accepts a spiral drawing image and returns a prediction.
+
+### Input format
+
+Both prediction endpoints expect:
+
+- `multipart/form-data`
+- a single file field named `file`
+
+### Example response
 
-**Response Example:**
 ```json
 {
   "drawing_type": "wave",
@@ -47,34 +162,178 @@ Accepts a drawn "spiral" pattern image overlay and calculates severity.
 }
 ```
 
+### Response fields
+
+- `drawing_type` - either `wave` or `spiral`
+- `raw_logit` - raw model output before sigmoid
+- `sigmoid_probability` - probability converted from the logit
+- `motor_impairment_score` - normalized score between 0 and 100
+- `severity_level` - severity category
+- `description` - human-readable interpretation
+- `is_parkinson` - boolean indicator derived from the severity level
+
 ---
 
-## 💻 Local Development
+## Severity Levels
 
-1. **Create Virtual Environment:**
-   ```bash
-   python -m venv venv
-   source venv/bin/activate
-   ```
+The API classifies the result into one of these labels:
 
-2. **Install Dependencies:**
-   ```bash
-   pip install -r requirements.txt
-   pip install fastapi uvicorn python-multipart
-   ```
+- **Normal Pattern** - no motor impairment detected
+- **Mild** - slight motor irregularities observed
+- **Moderate** - noticeable motor impairment detected
+- **High** - significant motor impairment observed
+- **Severe** - strong Parkinsonian motor patterns detected
 
-3. **Run the Server:**
-   ```bash
-   uvicorn main:app --reload
-   ```
+The exact score thresholds are defined in [services/predictor.py](services/predictor.py).
 
-4. Go to `http://127.0.0.1:8000/docs` to test the API directly using Swagger UI!
+---
+
+## Local Setup
+
+### 1. Create a virtual environment
+
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+
+### 2. Install dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+If needed, also install the runtime packages used by the API:
+
+```bash
+pip install fastapi uvicorn python-multipart
+```
+
+### 3. Run the server
+
+```bash
+uvicorn main:app --reload
+```
+
+### 4. Open the documentation
+
+Visit:
+
+```text
+http://127.0.0.1:8000/docs
+```
+
+This opens the interactive Swagger UI for testing the API.
+
+---
+
+## Example Requests
+
+### cURL example
+
+```bash
+curl -X POST "http://127.0.0.1:8000/predict/wave" \
+   -F "file=@test/wave.png"
+```
+
+### Spiral example
+
+```bash
+curl -X POST "http://127.0.0.1:8000/predict/spiral" \
+   -F "file=@test/spiral.png"
+```
+
+### Python example
+
+```python
+import requests
+
+url = "http://127.0.0.1:8000/predict/wave"
+
+with open("test/wave.png", "rb") as f:
+      files = {"file": f}
+      response = requests.post(url, files=files)
+
+print(response.json())
+```
 
 ---
 
-## ☁️ Hugging Face Deployment (Docker)
-This repository is pre-configured to automatically deploy as a **Docker Space** to Hugging Face via GitHub Actions.
 
-1. Any changes pushed to the `main` branch trigger `.github/workflows/deploy.yml`
-2. GitHub forcefully mirrors this repository to Hugging Face Hub securely using an injected `HF_TOKEN`.
-3. Hugging Face reads the attached `Dockerfile` and dynamically exposes the FastAPI service on Port `7860`.
+## Deployment
+
+### Docker
+
+The repository contains a Dockerfile that:
+
+- installs system dependencies required by OpenCV
+- installs the Python dependencies
+- runs the API on port `7860`
+
+### Hugging Face Spaces
+
+The repository is set up for deployment as a Docker Space on Hugging Face.
+
+Deployment flow:
+
+1. Push changes to the `main` branch
+2. GitHub Actions runs the workflow in [deploy.yml](.github/workflows/deploy.yml)
+3. The workflow pushes the repository to the Hugging Face Space repository
+4. Hugging Face rebuilds and redeploys the Space
+
+Target Hugging Face repository:
+
+`https://huggingface.co/spaces/xplorers/MIS_API`
+
+### Required secret
+
+The GitHub Actions workflow needs this secret:
+
+- `HF_TOKEN` - Hugging Face write token
+
+Make sure the token has permission to push to the target Space.
+
+---
+
+## Important Files
+
+### [main.py](main.py)
+
+Contains:
+
+- the FastAPI app
+- startup model loading
+- CORS configuration
+- image prediction endpoints
+
+### [services/predictor.py](services/predictor.py)
+
+Contains:
+
+- Hugging Face model download logic
+- image preprocessing
+- wave and spiral prediction functions
+- severity interpretation logic
+
+### [Dockerfile](Dockerfile)
+
+Contains:
+
+- Python base image
+- OpenCV system libraries
+- application startup command
+
+### [.github/workflows/deploy.yml](.github/workflows/deploy.yml)
+
+Contains:
+
+- GitHub Actions deployment logic
+- authenticated push to Hugging Face Spaces
+
+---
+
+## License and Usage
+
+No explicit license file is currently included in the repository.
+
+If you plan to publish or share the project publicly, add a license file and review the Hugging Face model and deployment permissions.