---
title: PAM-UmiNur
emoji: 🤖
colorFrom: pink
colorTo: purple
sdk: docker
sdk_version: "1.0"
app_file: app.py
pinned: false
license: mit
---

# 🤖 PAM - Privacy-First AI Assistant

**PAM** is your dual-personality AI assistant built for UmiNur's women's health ecosystem. She operates as both a warm, caring front-desk receptionist and a knowledgeable technical analyst.

---

## 💕 Meet the PAM Family

### Frontend PAM - Sweet Southern Receptionist
- **Personality**: Warm, comforting, encouraging
- **Voice**: Sweet southern charm with words of endearment (honey, boo, sugar, dear)
- **Role**: Patient-facing conversational agent
- **Handles**: Appointments, health inquiries, resource recommendations, general support

### Backend PAM - Nerdy Lab Assistant  
- **Personality**: Knowledgeable, enthusiastic, proactive
- **Voice**: Encouraging tech colleague who loves finding patterns
- **Role**: Technical infrastructure analyst
- **Handles**: SIEM alerts, PHI detection, log analysis, compliance monitoring

---

## 🚀 Features

### Frontend Capabilities
- ✅ **Appointment Management** - Schedule and manage patient appointments
- ✅ **Health Resource Matching** - Provide relevant resources based on symptoms
- ✅ **Emotional Support** - Detect distress and respond with empathy
- ✅ **Emergency Detection** - Flag urgent situations and provide appropriate guidance
- ✅ **Permission-Based Responses** - Respect content boundaries and escalate when needed

### Backend Capabilities
- ✅ **PHI Detection** - Scan text for Protected Health Information
- ✅ **Log Analysis** - Parse and classify system logs by severity
- ✅ **Compliance Monitoring** - Track regulatory compliance status
- ✅ **SIEM Integration** - Process security alerts and anomalies
- ✅ **Proactive Insights** - Flag issues before they escalate

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────┐
│         FastAPI Service Layer           │
│  (api_service.py - Port 7860)          │
└───────────┬─────────────┬───────────────┘
            │             │
    ┌───────▼─────┐  ┌───▼──────────┐
    │ Frontend PAM │  │ Backend PAM  │
    │  (Chat UI)   │  │ (Technical)  │
    └──────────────┘  └──────────────┘
           │                 │
    ┌──────▼─────────────────▼────────┐
    │  HuggingFace Inference API      │
    │  (Mistral, BART, BERT models)   │
    └─────────────────────────────────┘
```

---

## 📡 API Endpoints

### Core Endpoints
- **`GET /`** - Service information and navigation
- **`GET /health`** - Health check for both agents
- **`POST /ai/chat/`** - Frontend PAM (conversational)
- **`POST /ai/technical/`** - Backend PAM (technical analysis)
- **`POST /ai/unified/`** - Auto-routes based on intent

### Monitoring
- **`GET /metrics`** - Service metrics
- **`GET /docs`** - Interactive API documentation
- **`GET /debug/test-agents`** - Agent testing (dev only)

---

## 🔧 Setup & Deployment

### Prerequisites
- Python 3.10+
- HuggingFace account and API token
- Docker (for containerized deployment)

### Environment Variables
```bash
# Required
HF_READ_TOKEN=your_huggingface_token_here

# Optional
PAM_HOST=0.0.0.0
PAM_PORT=7860
PAM_LOG_LEVEL=info
```

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

# Set your HF token
export HF_READ_TOKEN="your_token_here"

# Run the service
python app.py
```

### Docker Deployment
```bash
# Build image
docker build -t pam-assistant .

# Run container
docker run -p 7860:7860 \
  -e HF_READ_TOKEN="your_token_here" \
  pam-assistant
```

### Hugging Face Spaces
1. Fork or create a new Space
2. Select "Docker" as SDK
3. Add `HF_READ_TOKEN` in Space settings (Settings → Repository secrets)
4. Push your code - auto-deployment will handle the rest!

---

## 📊 Data Files

PAM requires JSON data files in the `data/` directory:

- **`appointments.json`** - User appointment records
- **`resources.json`** - Health resource library
- **`follow_up.json`** - Follow-up tracking
- **`permissions.json`** - Content permission rules
- **`logs.json`** - System log entries
- **`compliance.json`** - Compliance checklist

---

## 🎯 Usage Examples

### Frontend PAM (Chat)
```python
# Request
POST /ai/chat/
{
  "user_input": "Hey PAM, I'm having some cramping",
  "user_id": "user_001"
}

# Response
{
  "reply": "Hey honey, I hear you. I've pulled together some helpful resources about what you're experiencing. Would you like me to also connect you with a nurse for a quick chat?",
  "intent": "health_symptoms_inquiry",
  "sentiment": {"label": "NEGATIVE", "score": 0.72},
  "agent_type": "frontend",
  "personality": "sweet_southern_receptionist"
}
```

### Backend PAM (Technical)
```python
# Request
POST /ai/technical/
{
  "user_input": "check compliance"
}

# Response
{
  "message": "🛡️ Great catch asking about this! Here's the compliance status:\n\n**Overall:** 4/5 checks passed (80.0%)\n\n**Action needed:** We have 1 items out of compliance:\n  • Data Encryption\n\nQuick side note - I can help you prioritize these if you want to tackle them systematically!",
  "compliance_report": ["✅ Hipaa Compliant", "✅ Gdpr Ready", ...],
  "compliance_rate": 80.0,
  "agent_type": "backend",
  "personality": "nerdy_lab_assistant"
}
```

---

## 🛡️ Privacy & Security

- **No persistent storage** of user conversations
- **PHI detection** before logging or storage
- **Permission-based content filtering**
- **Encryption-ready** for production deployment
- **HIPAA-aware** architecture

---

## 🤝 Contributing

PAM is part of the UmiNur ecosystem. For contributions or questions:
- Open an issue on GitHub
- Review the code structure before proposing changes
- Respect PAM's personality and voice guidelines

---

## 📝 License

MIT License - See LICENSE file for details

---

## 🙏 Acknowledgments

Built with:
- **FastAPI** - Modern Python web framework
- **HuggingFace** - Inference API and model hosting
- **Transformers** - NLP model library
- **Uvicorn** - ASGI server

---

## 📞 Support

For technical support or questions about PAM:
- 📧 Email: support@uminur.app
- 🌐 Website: https://www.uminur.app
- 📚 Docs: https://docs.uminur.app

---

**Made with 💕 for women's health by the UmiNur team**