README_HF.md

🏛️ Civic Issue Urgency Classifier - Hugging Face Spaces

Text-Only NLP Classifier for Government Civic Issue Prioritization

Live Demo • Quick Start • API • Model Info • Limitations

---

📖 Overview

Civic Issue Urgency Classifier is an AI-powered text analysis system that helps governments prioritize citizen-reported civic issues. It analyzes text descriptions and automatically assigns urgency levels (HIGH/MEDIUM/LOW) with confidence scores and actionable recommendations.

This is a text-only classifier. Image analysis is not currently supported.

---

🎯 Quick Start

Online (Hugging Face Spaces)

1. ✅ Open this Space (you're already here!)
2. 📝 Enter a civic issue description
3. 🎯 Click "Classify Urgency"
4. 📊 Get instant urgency assessment

Local Development

# Clone repo
git clone https://github.com/nitish-niraj/urgency-checker.git
cd urgency-checker

# Install dependencies
pip install -r requirements.txt

# Run FastAPI server
python -m uvicorn src.demo_api_browser:app --host 0.0.0.0 --port 8001 --reload

# Open browser
# http://localhost:8001

---

📊 API Usage

Classify a Civic Issue

Endpoint: POST /classify-urgency

Request:

{
  "text": "There are large, dangerous cracks in the road beside the university hospital blocking ambulance access — please fix immediately.",
  "location": "University Hospital, Main St",
  "category": "Infrastructure"
}

Response:

{
  "urgency_level": "HIGH",
  "urgency_score": 8.7,
  "confidence": 0.94,
  "recommended_department": "Emergency Services",
  "estimated_response_time": "Within 1 hour",
  "reasoning": "High urgency detected: Keywords indicate critical infrastructure issue affecting emergency services. Immediate action required.",
  "location_context": "Hospital vicinity",
  "safety_context": "Emergency"
}

Test Examples

🔴 HIGH Priority

"There are large, dangerous cracks in the road beside the university hospital blocking ambulance access — please fix immediately."

Expected: HIGH urgency (8.5+), Emergency Services

🟡 MEDIUM Priority

"The sidewalk has some uneven pavement in the downtown area; people are tripping occasionally."

Expected: MEDIUM urgency (5-7), Public Works

🟢 LOW Priority

"Minor paint fading and some litter along the park pathway; routine maintenance when convenient."

Expected: LOW urgency (2-4), Parks & Recreation

---

🤖 Model Information

Component	Details
Algorithm	RandomForest Ensemble (100 trees)
Text Features	TF-IDF vectorization + TextBlob sentiment
Training Data	Synthetic civic issue dataset
Model Size	~5MB
Response Time	<3 seconds
Language	English
Input	Text only (10-5000 characters)

---

⚙️ System Architecture

User Input (Text)
       ↓
Text Preprocessing (lowercase, tokenization)
       ↓
TF-IDF Vectorization + Sentiment Analysis
       ↓
Feature Engineering (urgency keywords, context)
       ↓
RandomForest Classifier
       ↓
Urgency Level + Score + Confidence
       ↓
Department Routing (based on category)
       ↓
Response Time Estimation
       ↓
JSON Output

---

⚠️ Limitations

• ✅ Text-only: No image analysis
• ✅ English only: Currently supports English language
• ✅ Synthetic data: Trained on synthetic civic issue examples
• ✅ No real-time: Demo-grade; not for production government systems
• ✅ No YOLO/Computer Vision: Image detection not available
• ✅ Stateless: No session management; each request is independent

---

🔧 Technical Stack

• Backend: FastAPI + Uvicorn
• ML: scikit-learn (RandomForest)
• NLP: TextBlob (sentiment analysis)
• Containerization: Docker
• Hosting: Hugging Face Spaces (Docker)

---

📈 Performance Metrics

Metric	Value
Avg Response Time	< 3 seconds
Model Accuracy	~95% (on test set)
Uptime	99%
Concurrent Requests	2-5 (HF Space tier)

---

🚀 Deployment

Deploy Your Own Space on Hugging Face

1. Fork the repository on GitHub
2. Create a new Space on Hugging Face
   • Go to https://huggingface.co/spaces/new
   • Select "Docker" as the Space type
   • Connect your GitHub repo
   • Choose "Dockerfile" as build type
3. Deploy - HF will auto-build from Dockerfile
4. Test - Use the live UI or API

Local Docker Build & Test

# Build image
docker build -t urgency-classifier:latest .

# Run locally
docker run -p 7860:7860 urgency-classifier:latest

# Test endpoint
curl -X POST http://localhost:7860/classify-urgency \
  -H "Content-Type: application/json" \
  -d '{"text":"Dangerous pothole blocking traffic"}'

---

📝 Example Requests (curl)

HIGH Priority

curl -X POST http://localhost:7860/classify-urgency \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Building facade crumbling - debris falling on pedestrians - URGENT",
    "location": "Downtown",
    "category": "Safety"
  }'

MEDIUM Priority

curl -X POST http://localhost:7860/classify-urgency \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Street light flickering at night; poses safety concern",
    "location": "Main Street",
    "category": "Infrastructure"
  }'

LOW Priority

curl -X POST http://localhost:7860/classify-urgency \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Small pothole in park path; cosmetic issue",
    "location": "Central Park",
    "category": "Maintenance"
  }'

---

🧪 Testing

API Endpoints

• GET / - Web UI
• GET /docs - Interactive API documentation (Swagger)
• GET /health - Health check
• GET /stats - System statistics
• POST /classify-urgency - Main classification endpoint

Try the API

# Health check
curl http://localhost:7860/health

# Get stats
curl http://localhost:7860/stats

# Classify an issue
curl -X POST http://localhost:7860/classify-urgency \
  -H "Content-Type: application/json" \
  -d '{"text":"Your civic issue description here"}'

---

📚 Resources

• Main Repository: https://github.com/nitish-niraj/urgency-checker
• Report Issues: https://github.com/nitish-niraj/urgency-checker/issues
• License: MIT

---

👤 Author

Nitish Niraj

• GitHub: @nitish-niraj
• Repository: urgency-checker

---

📄 License

MIT License - see LICENSE for details

---

⭐ Like this project? Star it on GitHub!

View on GitHub • Full Documentation