README.md

---

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**