Deploy to HF Spaces

.dockerignore

@@ -0,0 +1,51 @@
+# Virtual environment
+venv/
+env/
+.venv/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Environment files with secrets
+.env
+.env.local
+.env.*.local
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Documentation (optional - include if you want)
+# *.md
+# docs/
+
+# Test files (optional)
+# tests/
+# test_*.py
+
+# Logs
+*.log
+logs/
+
+# Database files (optional - include if you want example data)
+# data/*.db
+
+# Temporary files
+*.tmp
+*.temp
+

DEPLOY_HF_SPACES.md

@@ -0,0 +1,232 @@
+# Deploying IntegraChat to Hugging Face Spaces
+
+This guide walks you through deploying IntegraChat as a Hugging Face Space.
+
+## 📋 Prerequisites
+
+1. **Hugging Face Account**: Sign up at [huggingface.co](https://huggingface.co)
+2. **Hugging Face Token**: Get your token from [Settings → Access Tokens](https://huggingface.co/settings/tokens)
+3. **Required Services** (configure via environment variables):
+   - PostgreSQL with pgvector (for RAG storage)
+   - Ollama (local LLM) or Groq API (cloud LLM)
+   - Optional: Supabase (for production storage)
+   - Optional: Google Custom Search API (for web search)
+
+## 🚀 Step-by-Step Deployment
+
+### Step 1: Create a New Space
+
+1. Go to [https://huggingface.co/new-space](https://huggingface.co/new-space)
+2. Fill in the form:
+   - **Space name**: `integrachat` (or your preferred name)
+   - **SDK**: Select **Docker**
+   - **Hardware**: Choose based on your needs:
+     - **CPU basic** - For testing (free tier)
+     - **CPU upgrade** - Better performance (paid)
+     - **GPU** - If you need GPU acceleration (paid)
+   - **Visibility**: Public or Private
+3. Click **Create Space**
+
+### Step 2: Prepare Your Repository
+
+Your project structure should look like this:
+
+```
+IntegraChat/
+├── Dockerfile              ✅ (created)
+├── .dockerignore           ✅ (created)
+├── README_HF_SPACES.md     ✅ (created)
+├── requirements.txt        ✅ (already exists)
+├── app.py                  ✅ (already exists)
+├── env.example             ✅ (already exists)
+├── LICENSE                  ✅ (already exists)
+├── README.md               ✅ (already exists)
+├── assets/
+│   └── banner.png          ✅ (already exists)
+├── backend/                ✅ (entire directory)
+└── scripts/                ✅ (if you have any)
+```
+
+### Step 3: Push to Hugging Face
+
+#### Option A: Using Git (Recommended)
+
+```bash
+# Initialize git if not already done
+git init
+
+# Add Hugging Face remote
+git remote add hf https://huggingface.co/spaces/<your-username>/<space-name>
+
+# Add all files (except venv)
+git add Dockerfile .dockerignore README_HF_SPACES.md requirements.txt app.py env.example LICENSE README.md assets/ backend/ scripts/
+
+# Commit
+git commit -m "Initial commit for HF Spaces deployment"
+
+# Push to Hugging Face
+git push hf main
+```
+
+#### Option B: Using Hugging Face Web Interface
+
+1. Go to your Space page
+2. Click **Files and versions** tab
+3. Click **Upload files**
+4. Upload all necessary files (drag and drop or select files)
+
+### Step 4: Configure Environment Variables
+
+1. Go to your Space page
+2. Click **Settings** tab
+3. Scroll to **Repository secrets** section
+4. Add the following environment variables:
+
+#### Required Variables
+
+```env
+POSTGRESQL_URL=postgresql://user:password@host:port/database
+OLLAMA_URL=http://your-ollama-server:11434
+OLLAMA_MODEL=llama3.1:latest
+```
+
+**OR** (if using Groq instead of Ollama):
+
+```env
+GROQ_API_KEY=your_groq_api_key
+LLM_BACKEND=groq
+```
+
+#### Optional Variables
+
+```env
+# Supabase (for production storage)
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=your_service_role_key
+
+# Google Custom Search (for web search)
+GOOGLE_SEARCH_API_KEY=your_google_api_key
+GOOGLE_SEARCH_CX_ID=your_search_engine_id
+
+# MCP Server Configuration
+MCP_PORT=8900
+MCP_HOST=0.0.0.0
+
+# API Configuration
+API_PORT=8000
+BACKEND_BASE_URL=http://localhost:8000
+
+# Memory Configuration
+MCP_MEMORY_MAX_ITEMS=10
+MCP_MEMORY_TTL_SECONDS=900
+
+# Logging
+LOG_LEVEL=info
+APP_ENV=production
+```
+
+### Step 5: Wait for Build
+
+1. After pushing, Hugging Face will automatically start building your Docker image
+2. You can monitor the build progress in the **Logs** tab
+3. Build typically takes 5-10 minutes for the first time
+4. Once built, your Space will be available at:
+   `https://huggingface.co/spaces/<your-username>/<space-name>`
+
+### Step 6: Verify Deployment
+
+1. **Check Logs**: Go to the **Logs** tab to see if all services started correctly
+2. **Test UI**: Open your Space URL and verify the Gradio UI loads
+3. **Test API**: Try accessing `https://<your-space-url>/api/docs` for FastAPI docs
+4. **Test Health**: Check `https://<your-space-url>/api/health` for backend health
+
+## 🔧 Troubleshooting
+
+### Build Fails
+
+- **Check Dockerfile syntax**: Ensure all commands are valid
+- **Check requirements.txt**: Verify all packages are available on PyPI
+- **Check logs**: Review build logs for specific errors
+- **Common issues**:
+  - Missing system dependencies → Add to `apt-get install` in Dockerfile
+  - Python version mismatch → Update `FROM python:3.10-slim` if needed
+  - Port conflicts → Ensure ports 7860, 8000, 8900 are exposed
+
+### Services Not Starting
+
+- **Check environment variables**: Ensure all required vars are set
+- **Check service logs**: Review logs for MCP server and FastAPI errors
+- **Database connection**: Verify PostgreSQL URL is correct and accessible
+- **LLM connection**: Verify Ollama URL or Groq API key is valid
+
+### UI Not Loading
+
+- **Check Gradio logs**: Look for errors in the Logs tab
+- **Check port binding**: Ensure Gradio binds to `0.0.0.0:7860`
+- **Check backend connection**: Verify `BACKEND_BASE_URL` is correct
+
+### API Endpoints Not Working
+
+- **Check FastAPI logs**: Review backend startup logs
+- **Check MCP server**: Ensure MCP server is running on port 8900
+- **Check CORS**: Verify CORS middleware is configured correctly
+- **Check headers**: Ensure `x-tenant-id` and `x-user-role` headers are sent
+
+## 📝 Important Notes
+
+1. **Port Configuration**: 
+   - Hugging Face Spaces automatically maps port 7860 to the public URL
+   - Internal services (FastAPI on 8000, MCP on 8900) are accessible within the container
+   - Use `localhost` for inter-service communication
+
+2. **Database Access**:
+   - Your PostgreSQL database must be accessible from Hugging Face's servers
+   - Consider using a cloud database (Supabase, AWS RDS, etc.)
+   - Ensure firewall rules allow connections from Hugging Face IPs
+
+3. **LLM Access**:
+   - If using Ollama, it must be accessible from Hugging Face servers
+   - Consider using Groq API for cloud-based LLM access
+   - Or use Hugging Face's Inference API
+
+4. **Resource Limits**:
+   - Free tier has CPU and memory limits
+   - Consider upgrading for production use
+   - Monitor resource usage in the Space settings
+
+5. **Secrets Management**:
+   - Never commit `.env` files with secrets
+   - Use Hugging Face Space secrets for sensitive data
+   - Use `env.example` as a template
+
+## 🎯 Next Steps
+
+1. **Customize README**: Update `README_HF_SPACES.md` with your specific details
+2. **Add Banner**: Upload a banner image to `assets/banner.png`
+3. **Test Thoroughly**: Test all features in the deployed environment
+4. **Monitor Usage**: Check Space analytics for usage patterns
+5. **Update Documentation**: Keep documentation in sync with deployment
+
+## 📚 Additional Resources
+
+- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Docker on Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Environment Variables Guide](https://huggingface.co/docs/hub/spaces-config#environment-variables)
+
+## ✅ Checklist
+
+Before deploying, ensure:
+
+- [ ] Dockerfile is present and valid
+- [ ] .dockerignore excludes venv and .env
+- [ ] requirements.txt includes all dependencies
+- [ ] Environment variables are documented
+- [ ] Database is accessible from Hugging Face servers
+- [ ] LLM service is configured (Ollama or Groq)
+- [ ] README_HF_SPACES.md is customized
+- [ ] All code is committed and pushed
+
+---
+
+**Need Help?** Check the [Troubleshooting](#-troubleshooting) section or open an issue in the repository.
+

Dockerfile

@@ -0,0 +1,100 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    postgresql-client \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create data directory for SQLite fallback
+RUN mkdir -p /app/data
+
+# Expose ports
+# - 7860: Gradio UI (default HF Spaces port)
+# - 8000: FastAPI backend
+# - 8900: MCP server
+EXPOSE 7860 8000 8900
+
+# Set environment variables with defaults
+ENV PYTHONPATH=/app
+ENV API_PORT=8000
+ENV MCP_PORT=8900
+ENV BACKEND_BASE_URL=http://localhost:8000
+ENV RAG_MCP_URL=http://localhost:8900/rag
+ENV WEB_MCP_URL=http://localhost:8900/web
+ENV ADMIN_MCP_URL=http://localhost:8900/admin
+
+# Create startup script that runs all services
+RUN echo '#!/bin/bash\n\
+set -e\n\
+\n\
+# Function to wait for a service to be ready\n\
+wait_for_service() {\n\
+    local url=$1\n\
+    local max_attempts=30\n\
+    local attempt=0\n\
+    \n\
+    echo "Waiting for $url to be ready..."\n\
+    while [ $attempt -lt $max_attempts ]; do\n\
+        if curl -s -f "$url" > /dev/null 2>&1; then\n\
+            echo "$url is ready!"\n\
+            return 0\n\
+        fi\n\
+        attempt=$((attempt + 1))\n\
+        sleep 1\n\
+    done\n\
+    \n\
+    echo "Warning: $url did not become ready after $max_attempts attempts"\n\
+    return 1\n\
+}\n\
+\n\
+# Start MCP server in background\n\
+echo "Starting MCP server on port $MCP_PORT..."\n\
+python -m backend.mcp_server.server &\n\
+MCP_PID=$!\n\
+\n\
+# Wait for MCP server to be ready\n\
+sleep 5\n\
+if ! kill -0 $MCP_PID 2>/dev/null; then\n\
+    echo "Error: MCP server failed to start"\n\
+    exit 1\n\
+fi\n\
+\n\
+# Start FastAPI backend in background\n\
+echo "Starting FastAPI backend on port $API_PORT..."\n\
+uvicorn backend.api.main:app --host 0.0.0.0 --port $API_PORT &\n\
+API_PID=$!\n\
+\n\
+# Wait for FastAPI to be ready\n\
+sleep 5\n\
+if ! kill -0 $API_PID 2>/dev/null; then\n\
+    echo "Error: FastAPI backend failed to start"\n\
+    exit 1\n\
+fi\n\
+\n\
+# Wait for health check\n\
+wait_for_service "http://localhost:$API_PORT/health" || true\n\
+\n\
+# Start Gradio UI (foreground - this is the main process)\n\
+echo "Starting Gradio UI on port 7860..."\n\
+echo "All services are running:"\n\
+echo "  - MCP Server: http://localhost:$MCP_PORT"\n\
+echo "  - FastAPI Backend: http://localhost:$API_PORT"\n\
+echo "  - Gradio UI: http://localhost:7860"\n\
+python app.py\n\
+' > /app/start.sh && chmod +x /app/start.sh
+
+# Use the startup script as entrypoint
+CMD ["/app/start.sh"]
+

HF_SPACES_SUMMARY.md

@@ -0,0 +1,139 @@
+# ✅ Hugging Face Spaces Deployment - Complete!
+
+Your IntegraChat project is now ready to deploy to Hugging Face Spaces! Here's what has been created:
+
+## 📦 Files Created
+
+### 1. **Dockerfile** ✅
+- Multi-service Docker container
+- Runs MCP server, FastAPI backend, and Gradio UI
+- Includes health checks and service coordination
+- Optimized for Hugging Face Spaces
+
+### 2. **.dockerignore** ✅
+- Excludes `venv/`, `.env`, and other unnecessary files
+- Reduces build size and prevents secret leaks
+
+### 3. **README_HF_SPACES.md** ✅
+- Optimized README for Hugging Face Spaces
+- Includes Space metadata (emoji, colors, SDK type)
+- Quick start guide and feature overview
+
+### 4. **DEPLOY_HF_SPACES.md** ✅
+- Complete step-by-step deployment guide
+- Troubleshooting section
+- Environment variable configuration
+- Best practices
+
+## 🚀 Quick Deployment Steps
+
+1. **Create Space**: Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+   - Choose **Docker** as SDK
+   - Set hardware (CPU basic for testing, upgrade for production)
+
+2. **Push Code**:
+   ```bash
+   git init
+   git remote add hf https://huggingface.co/spaces/<username>/<space-name>
+   git add Dockerfile .dockerignore README_HF_SPACES.md requirements.txt app.py env.example LICENSE README.md assets/ backend/ scripts/
+   git commit -m "Deploy to HF Spaces"
+   git push hf main
+   ```
+
+3. **Configure Secrets**: In Space Settings → Repository secrets, add:
+   - `POSTGRESQL_URL`
+   - `OLLAMA_URL` (or `GROQ_API_KEY`)
+   - `OLLAMA_MODEL`
+   - Optional: `SUPABASE_URL`, `SUPABASE_SERVICE_KEY`, etc.
+
+4. **Wait for Build**: Monitor build progress in the Logs tab (5-10 minutes)
+
+5. **Access Your Space**: `https://huggingface.co/spaces/<username>/<space-name>`
+
+## 🏗️ Architecture in Docker
+
+The Dockerfile runs three services:
+
+```
+┌─────────────────────────────────────┐
+│         Docker Container            │
+│                                     │
+│  ┌──────────────┐                  │
+│  │ MCP Server   │  Port 8900       │
+│  │ (Background) │                   │
+│  └──────────────┘                   │
+│                                     │
+│  ┌──────────────┐                  │
+│  │ FastAPI      │  Port 8000       │
+│  │ (Background) │                   │
+│  └──────────────┘                   │
+│                                     │
+│  ┌──────────────┐                  │
+│  │ Gradio UI    │  Port 7860       │
+│  │ (Foreground) │  ← Main Entry    │
+│  └──────────────┘                   │
+└─────────────────────────────────────┘
+```
+
+## 📋 What's Included
+
+✅ **Dockerfile** - Production-ready multi-service container  
+✅ **.dockerignore** - Excludes unnecessary files  
+✅ **README_HF_SPACES.md** - Space-optimized documentation  
+✅ **DEPLOY_HF_SPACES.md** - Complete deployment guide  
+✅ **Health checks** - Service readiness verification  
+✅ **Error handling** - Graceful service startup  
+✅ **Environment variables** - Configurable via HF Space settings  
+
+## 🔧 Configuration
+
+All configuration is done via environment variables in Hugging Face Space settings:
+
+### Required
+- `POSTGRESQL_URL` - Database connection
+- `OLLAMA_URL` + `OLLAMA_MODEL` - OR `GROQ_API_KEY`
+
+### Optional
+- `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` - Production storage
+- `GOOGLE_SEARCH_API_KEY` + `GOOGLE_SEARCH_CX_ID` - Web search
+- `MCP_PORT`, `API_PORT` - Service ports (defaults work)
+
+## 📚 Next Steps
+
+1. **Review Files**: Check all created files match your needs
+2. **Test Locally**: Build Docker image locally to test:
+   ```bash
+   docker build -t integrachat .
+   docker run -p 7860:7860 -p 8000:8000 -p 8900:8900 integrachat
+   ```
+3. **Deploy**: Follow steps in `DEPLOY_HF_SPACES.md`
+4. **Monitor**: Check logs and analytics after deployment
+
+## 🎯 Key Features
+
+- ✅ **Multi-service orchestration** - All services run in one container
+- ✅ **Health checks** - Services wait for each other to be ready
+- ✅ **Error handling** - Graceful failures and logging
+- ✅ **Production-ready** - Optimized for Hugging Face Spaces
+- ✅ **Configurable** - All settings via environment variables
+
+## 💡 Tips
+
+1. **First Build**: May take 10-15 minutes (downloads dependencies)
+2. **Subsequent Builds**: Faster (cached layers)
+3. **Logs**: Check Logs tab for detailed startup information
+4. **Database**: Ensure PostgreSQL is accessible from HF servers
+5. **LLM**: Consider Groq API for cloud-based LLM (no local server needed)
+
+## 🆘 Need Help?
+
+- Check `DEPLOY_HF_SPACES.md` for detailed troubleshooting
+- Review Dockerfile comments for service configuration
+- Check Hugging Face Spaces documentation for platform-specific issues
+
+---
+
+**Your project is ready to deploy! 🚀**
+
+Follow the steps in `DEPLOY_HF_SPACES.md` to get started.
+

README_HF_SPACES.md

@@ -0,0 +1,114 @@
+---
+title: IntegraChat
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# IntegraChat — Enterprise MCP Autonomous Agent Platform
+
+**IntegraChat** is an enterprise-grade, multi-tenant AI platform that demonstrates the full capabilities of the **Model Context Protocol (MCP)** in a production-style environment.
+
+## 🚀 Quick Start
+
+This Hugging Face Space runs the complete IntegraChat stack:
+- **Gradio UI** on port 7860 (main interface)
+- **FastAPI Backend** on port 8000 (API endpoints)
+- **Unified MCP Server** on port 8900 (RAG/Web/Admin tools)
+
+## ✨ Features
+
+- 🤖 **Autonomous Multi-Step MCP Agents** – Intelligent tool-aware agent with conversation memory
+- 📚 **Enhanced Knowledge Base Management** – Upload documents (PDF/DOCX/TXT/MD) with AI-generated metadata
+- 🔍 **Optimized RAG Search** – Cross-encoder re-ranking for improved accuracy
+- 🛡️ **Enterprise Admin Governance** – Regex-based red-flag detection with LLM enhancement
+- 📊 **Comprehensive Analytics** – Real-time visualizations and tenant-level metrics
+- 🌐 **Live Web Search** – Google Programmable Search integration
+- 🏢 **Multi-Tenant Isolation** – Complete tenant isolation with role-based access control
+
+## 📖 Usage
+
+1. **Enter Tenant ID**: Set your tenant ID in the UI (top of the page)
+2. **Select Role**: Choose your role (viewer, editor, admin, owner) from the dropdown
+3. **Start Chatting**: Use the Chat tab to interact with the agent
+4. **Ingest Documents**: Upload documents in the Document Ingestion tab (requires editor+ role)
+5. **Manage Rules**: Add admin rules in the Admin Rules tab (requires admin+ role)
+6. **View Analytics**: Check analytics in the Admin Analytics tab
+
+## 🔧 Configuration
+
+Set these environment variables in your Hugging Face Space settings:
+
+### Required
+- `POSTGRESQL_URL` - PostgreSQL connection string with pgvector extension
+- `OLLAMA_URL` - Ollama server URL (or use Groq API)
+- `OLLAMA_MODEL` - Model name (e.g., `llama3.1:latest`)
+
+### Optional
+- `SUPABASE_URL` - Supabase project URL (for production storage)
+- `SUPABASE_SERVICE_KEY` - Supabase service role key
+- `GOOGLE_SEARCH_API_KEY` - Google Custom Search API key
+- `GOOGLE_SEARCH_CX_ID` - Google Custom Search Engine ID
+- `GROQ_API_KEY` - Groq API key (alternative to Ollama)
+- `LLM_BACKEND` - `ollama` or `groq` (default: `ollama`)
+
+## 📚 API Endpoints
+
+The FastAPI backend is available at `/api` (relative to the Space URL):
+
+- `POST /api/agent/message` - Main chat endpoint
+- `POST /api/rag/ingest-document` - Ingest documents
+- `GET /api/rag/list` - List documents
+- `POST /api/admin/rules` - Manage admin rules
+- `GET /api/analytics/overview` - View analytics
+
+Full API docs available at `/api/docs` when the backend is running.
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐
+│   Gradio UI     │  Port 7860
+│  (Main Entry)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  FastAPI Backend│  Port 8000
+└────────┬────────┘
+         │
+         ├──► MCP Server (Port 8900)
+         │    ├── RAG Tools
+         │    ├── Web Tools
+         │    └── Admin Tools
+         │
+         ├──► PostgreSQL (RAG)
+         ├──► Supabase/SQLite (Rules & Analytics)
+         └──► LLM (Ollama/Groq)
+```
+
+## 🔐 Role-Based Access Control
+
+- **viewer** - Basic chat access
+- **editor** - Can ingest documents
+- **admin** - Can manage rules and delete documents
+- **owner** - Full system access
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Full Documentation](README.md)
+- [Backend Documentation](backend/README.md)
+
+---
+
+**Made with ❤️ for the MCP Hackathon**
+