README.md

metadata

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

# Required
HF_READ_TOKEN=your_huggingface_token_here

# Optional
PAM_HOST=0.0.0.0
PAM_PORT=7860
PAM_LOG_LEVEL=info

Local Development

# 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

# 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)

# 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)

# 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