README.md

---
title: Pneumonia Space
emoji: 🫁
colorFrom: blue
colorTo: green
sdk: docker
app_port: 5000
pinned: false
license: mit
---

# 🫁 Pneumonia Risk Assessment API

AI-powered API for assessing pneumonia risk from respiratory audio recordings.

## 🚀 Features

- **HeAR Model Integration**: Uses Google's Health Acoustic Representations model
- **Risk Scoring**: Provides probability-based risk assessment (not diagnostic)
- **Fallback System**: Uses librosa-based features if HeAR model unavailable
- **REST API**: Simple Flask endpoint for audio file uploads

## 🔑 Setup

### Hugging Face Authentication

The HeAR model requires Hugging Face authentication. Set your token as an environment variable:

```bash
export HF_TOKEN="your_huggingface_token_here"
```

Or login using the CLI:

```bash
huggingface-cli login
```

Get your token from: https://huggingface.co/settings/tokens

### Running Locally

```bash
# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

### Using Docker

```bash
# Build the image
docker build -t pneumonia-api .

# Run with HF token
docker run -p 5000:5000 -e HF_TOKEN="your_token" pneumonia-api
```

## 📡 API Usage

**Endpoint**: `POST /predict_pneumonia`

**Request**: Multipart form data with `audio_file`

**Response**:
```json
{
  "filename": "recording.wav",
  "pneumonia_risk_score": 0.7234,
  "risk_level": "High",
  "note": "This is an AI assessment, not a medical diagnosis. Consult a healthcare professional."
}
```

**Example with curl**:
```bash
curl -X POST -F "audio_file=@recording.wav" http://localhost:5000/predict_pneumonia
```

## ⚠️ Disclaimer

This tool provides risk assessment scores, not medical diagnoses. Always consult healthcare professionals for medical decisions.

## 📄 License

MIT License

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference