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](https://huggingface.co)
2. **API Keys**: Get your Nebius AI API key from [studio.nebius.ai](https://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](https://huggingface.co/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

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

### 3. Copy KnowledgeBridge Files

```bash
# 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:

```bash
# 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:

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

### 6. Commit and Push

```bash
# 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:
```bash
# 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](https://huggingface.co/docs/hub/spaces)
- [Docker for Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [Agents-MCP-Hackathon](https://huggingface.co/Agents-MCP-Hackathon)
- [Nebius AI Documentation](https://docs.nebius.ai/)

Good luck with your hackathon submission! 🚀