DEPLOYMENT.md

Aglimate Deployment Guide for HuggingFace Spaces

Pre-Deployment Checklist

✅ Git Remote Set: https://huggingface.co/spaces/nexusbert/Aglimate ✅ Dockerfile: Configured for port 7860 ✅ Requirements: All dependencies listed ✅ .gitignore: Excludes venv, models, cache files ✅ README.md: Updated with Space metadata

Required Environment Variables

Set these in your HuggingFace Space settings (Settings → Variables and secrets):

1. WEATHER_API_KEY (Required for weather features)

   • Get from: https://www.weatherapi.com/

2. EXPERT_MODEL_NAME (Optional)

   • Default: Qwen/Qwen1.5-1.8B
   • Can override if needed

3. WEATHER_FORECAST_DAYS (Optional)

   • Default: 3
   • Controls default forecast horizon for internal weather summaries.

4. WEATHER_AQI (Optional)

   • Default: yes
   • Set to no to disable air quality data in WeatherAPI responses used internally.

5. WEATHER_ALERTS (Optional)

   • Default: yes
   • Controls whether alerts are requested from WeatherAPI in internal calls.

Deployment Steps

1. Stage Files for Commit

git add .

This will add:

• ✅ All application code (app/)
• ✅ Dockerfile
• ✅ requirements.txt
• ✅ README.md
• ✅ Configuration files

This will NOT add (thanks to .gitignore):

• ❌ venv/ folder
• ❌ .env files
• ❌ Model files (loaded at runtime)
• ❌ Cache files

2. Commit Changes

git commit -m "Initial Aglimate deployment - CPU optimized"

3. Push to HuggingFace Spaces

git push origin main

Note: When prompted for password, use your HuggingFace access token with write permissions:

• Generate token: https://huggingface.co/settings/tokens
• Use token as password when pushing

4. Monitor Deployment

1. Go to: https://huggingface.co/spaces/nexusbert/Aglimate
2. Check the "Logs" tab for build progress
3. First build may take 5-10 minutes
4. Subsequent builds are faster (~2-3 minutes)

Post-Deployment

Verify Deployment

1. Health Check: Visit https://nexusbert-aglimate.hf.space/

   • Should return a JSON status message indicating the Aglimate backend is running.

2. Test Endpoints:

   • /ask - Multilingual farming Q&A
   • /advise - Multimodal climate-resilient advisory (text + optional photo + GPS)
   • /weather/current - Direct realtime weather + AQI
   • /weather/forecast - Forecast + alerts for a location
   • /weather-alerts - Alerts-only view for climate risk UIs

Expected Behavior

• Startup Time: <5 seconds (models load lazily)
• First Request: 5-15 seconds (loads Qwen 1.8B model)
• Subsequent Requests: <2 seconds
• Memory Usage: ~4-8GB when models loaded

Troubleshooting

Issue: Build fails

• Solution: Check Dockerfile syntax, ensure all files are committed

Issue: App crashes on startup

• Solution: Check logs, verify environment variables are set

Issue: Models not loading

• Solution: Check HuggingFace cache permissions, verify model names

Issue: Out of memory

• Solution: Models are already optimized (1.8B), but you can:
  • Use smaller models
  • Increase Space resources (if available)

Space Configuration

Your Space is configured as:

• SDK: Docker
• Port: 7860 (required by HuggingFace)
• Hardware: CPU (optimized for this)
• Auto-restart: Enabled

Updates

To update your Space:

git add .
git commit -m "Update: [describe changes]"
git push origin main

HuggingFace will automatically rebuild and redeploy.

---

Ready to deploy? Run the commands in section "Deployment Steps" above!