DEPLOYMENT_GUIDE.md

🚀 MedeX - Deployment Instructions for Hugging Face Spaces

Prerequisites

• Hugging Face account
• Moonshot AI API Key (Get from: https://platform.moonshot.ai/)

Step-by-Step Deployment

1. Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: medex-medical-ai (or your preferred name)
   • License: MIT
   • Select SDK: Docker (IMPORTANT!)
   • Space hardware: CPU Basic (free tier works fine)
   • Visibility: Public or Private (your choice)

2. Configure Space Settings

After creating the Space:

1. Go to Settings tab
2. Under Repository secrets, add:
   • Name: KIMI_API_KEY
   • Value: Your Moonshot AI API key
   • Click "Add new secret"

3. Upload Files

You have two options:

Option A: Git Clone & Push (Recommended)

# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy all MedeX files to the repository
# (Copy all files from MedeX-main folder)

# Stage and commit
git add .
git commit -m "Initial MedeX deployment"

# Push to HF Spaces
git push

Option B: Web Upload

1. Go to Files tab in your Space
2. Click "Add file" → "Upload files"
3. Upload ALL files from MedeX-main folder:
   • streamlit_app.py
   • Dockerfile
   • .dockerignore
   • requirements.txt
   • config.py
   • MEDEX_ULTIMATE_RAG.py
   • medical_knowledge_base.py
   • medical_rag_system.py
   • pharmaceutical_database.py
   • banner.png
   • .streamlit/config.toml
   • core/ folder (all files)
   • rag_cache/ folder
   • README_HF.md (rename to README.md in the Space)
4. Commit the changes

4. Update README.md Metadata

Make sure your Space's README.md starts with this metadata:

---
title: MedeX - Medical AI System
emoji: 🏥
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
---

5. Wait for Build

1. The Space will automatically start building
2. Monitor the build logs in the "Logs" tab
3. Build typically takes 3-5 minutes
4. Once complete, the Space will automatically start

6. Verify Deployment

1. Open your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
2. You should see the MedeX interface
3. Test with a query: "¿Qué es la diabetes tipo 2?"
4. Verify that responses are being generated

Troubleshooting

Build Fails

Issue: Docker build fails Solution:

• Check build logs for specific error
• Ensure all files were uploaded correctly
• Verify Dockerfile syntax

API Key Not Working

Issue: "Error initializing MedeX" or API errors Solution:

• Verify KIMI_API_KEY is set in Space secrets
• Check API key is valid on Moonshot AI platform
• Restart the Space

Space Not Starting

Issue: Space shows "Runtime Error" Solution:

• Check that port 7860 is specified in Dockerfile
• Verify streamlit_app.py exists
• Review application logs

Memory Issues

Issue: Out of memory errors Solution:

• Upgrade to better hardware in Space settings
• Consider CPU Upgrade or T4 GPU

File Structure Required

YOUR_SPACE/
├── README.md (with metadata)
├── Dockerfile
├── .dockerignore
├── requirements.txt
├── streamlit_app.py
├── config.py
├── MEDEX_ULTIMATE_RAG.py
├── medical_knowledge_base.py
├── medical_rag_system.py
├── pharmaceutical_database.py
├── banner.png
├── api_key.txt (optional, empty is fine)
├── .streamlit/
│   └── config.toml
├── core/
│   ├── ai_engine.py
│   ├── enhanced_ai_engine.py
│   ├── pure_kimi_medex.py
│   └── real_kimi_client.py
└── rag_cache/
    └── (empty or with rag_index.pkl)

Configuration Options

Environment Variables (Optional)

You can set these in Space settings:

• KIMI_API_KEY: Your Moonshot AI API key (REQUIRED)
• MOONSHOT_BASE_URL: API base URL (default: https://api.moonshot.ai/v1)

Hardware Recommendations

• CPU Basic (Free): Good for testing and light usage
• CPU Upgrade: Better performance for multiple users
• T4 GPU: Recommended for production with high traffic

Post-Deployment

Test Functionality

1. Patient Query: "Me duele el pecho y estoy preocupado"
2. Professional Query: "Paciente 65 años con dolor precordial"
3. Emergency Query: "Dolor torácico intenso, no puedo respirar"
4. Educational Query: "¿Qué es la hipertensión arterial?"

Monitor Performance

• Check "Logs" tab regularly
• Monitor response times
• Review error logs if issues occur

Share Your Space

• Share URL with colleagues
• Embed in your website using iframe
• Create duplicates for specific use cases

Support

For issues:

1. Check Hugging Face Spaces documentation
2. Review Moonshot AI API documentation
3. Check build and application logs
4. Contact support if needed

Security Notes

⚠️ IMPORTANT:

• Never commit API keys to git
• Use HF Spaces secrets for sensitive data
• Keep .gitignore updated
• Regularly rotate API keys

Updates

To update your deployed Space:

# Make changes locally
# Commit and push
git add .
git commit -m "Update description"
git push

The Space will automatically rebuild with your changes.

---

Quick Reference

Action	Command/Location
View Space	https://huggingface.co/spaces/USERNAME/SPACENAME
Edit files	Files tab or git push
View logs	Logs tab
Settings	Settings tab
Restart	Settings → Restart Space

---

Ready to deploy? Follow the steps above and your MedeX Space will be live in minutes! 🚀