docs/archive/HUGGINGFACE_DEPLOYMENT.md

🚀 Deploying KnowledgeBridge to Hugging Face Spaces

🤖 Track 3: Agentic Demo Showcase

This guide will help you deploy KnowledgeBridge to Hugging Face Spaces for the Agents-MCP-Hackathon Track 3: Agentic Demo Showcase - demonstrating the incredible power of AI agents working together!

🎯 Prerequisites

1. Hugging Face Account: Sign up at huggingface.co
2. API Keys: Get your Nebius AI API key from studio.nebius.ai
3. Git: Ensure git is installed on your system

📦 Step-by-Step Deployment

1. Create a New Hugging Face Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: KnowledgeBridge
   • License: MIT
   • Space SDK: Docker
   • Visibility: Public
4. Click "Create Space"

2. Clone Your New Space Repository

# Clone the empty space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/KnowledgeBridge
cd KnowledgeBridge

3. Copy KnowledgeBridge Files

# Copy all files from your local KnowledgeBridge project
cp -r /path/to/your/KnowledgeBridge/* .
cp -r /path/to/your/KnowledgeBridge/.* . 2>/dev/null || true

# Make sure you have these key files:
ls -la
# Should see: Dockerfile, package.json, .env.example, README.md, etc.

4. Configure Environment Variables

1. Go to your Space settings on Hugging Face
2. Navigate to "Variables and secrets"
3. Add these environment variables:

# Required
NEBIUS_API_KEY=your_actual_nebius_api_key_here
NODE_ENV=production
PORT=7860

# Optional but recommended
GITHUB_TOKEN=your_github_token_here
MODAL_TOKEN_ID=your_modal_token_id
MODAL_TOKEN_SECRET=your_modal_token_secret

5. Update README.md

Replace YOUR_USERNAME in the README.md with your actual Hugging Face username:

**Live Demo**: [Try KnowledgeBridge on Hugging Face Spaces](https://huggingface.co/spaces/YOUR_USERNAME/KnowledgeBridge)

6. Commit and Push

# Add all files
git add .

# Commit with a descriptive message
git commit -m "🚀 Deploy KnowledgeBridge to Hugging Face Spaces

- AI-enhanced knowledge discovery platform
- Multi-source search (GitHub, Wikipedia, ArXiv)
- Interactive knowledge graphs and visualizations
- Enterprise-grade security and performance
- Built for Agents-MCP-Hackathon"

# Push to deploy
git push origin main

7. Monitor Deployment

1. Go to your Space page: https://huggingface.co/spaces/YOUR_USERNAME/KnowledgeBridge
2. You'll see the build logs in real-time
3. The deployment typically takes 3-5 minutes
4. Once complete, your app will be available at the Space URL

✅ Verification Steps

After deployment, verify these features work:

1. Health Check: Visit /api/health - should show all services healthy
2. Search: Try searching for "machine learning"
3. AI Assistant: Click the 🤖 button and test explanations
4. Knowledge Graph: Navigate to the Knowledge Graph tab
5. Document Analysis: Test with sample content

🔧 Troubleshooting

Common Issues:

1. Build Fails:

   • Check the build logs in your Space
   • Ensure all dependencies are in package.json
   • Verify Dockerfile syntax

2. App Doesn't Start:

   • Check environment variables are set correctly
   • Ensure PORT=7860 is configured
   • Verify the start script in package.json

3. API Errors:

   • Ensure NEBIUS_API_KEY is valid and has credits
   • Check the logs for specific error messages
   • Verify network connectivity to external APIs

Debug Commands:

If you need to debug, you can check logs:

# View recent logs (if you have CLI access)
docker logs <container_id>

🎉 Success!

Once deployed successfully, your KnowledgeBridge app will be live at: https://huggingface.co/spaces/YOUR_USERNAME/KnowledgeBridge

Share this URL in your hackathon submission!

📝 Hackathon Submission Checklist

• ✅ App deployed and accessible on Hugging Face Spaces
• ✅ All core features working (search, AI assistant, knowledge graph)
• ✅ Environment variables configured securely
• ✅ README updated with live demo link
• ✅ Submission includes Space URL
• ✅ All APIs responding correctly

🔗 Useful Links

• Hugging Face Spaces Documentation
• Docker for Spaces Guide
• Agents-MCP-Hackathon
• Nebius AI Documentation

Good luck with your hackathon submission! 🚀