Skip to content

atanasovmi/RedHatMentorBot

BranchesTags

Repository files navigation

Open Source Mentor Bot

A web-based chatbot interface for the Open Source Mentor Bot hackathon project. This application allows users to upload documentation files, vectorize them, and interact with an AI mentor powered by LiteMAAS and Qdrant vector database.

🎯 Features

  • File Upload & Vectorization: Upload PDF, TXT, MD, and DOCX files
  • Semantic Search: Find relevant documentation chunks using Qdrant vector database
  • Chat Interface: Interactive conversation with AI mentor
  • Dark Mode: Toggle between light and dark themes
  • Real-time Processing: Progress tracking for file uploads
  • Statistics Dashboard: View vectorization metrics
  • Responsive Design: Works on desktop and mobile devices
  • Red Hat Values: Built with open collaboration principles

🏗️ Architecture

┌─────────────────────┐
│   Frontend (React)  │
│  - File Upload      │
│  - Chat Interface   │
│  - Vectorization UI │
└──────────┬──────────┘
           │ HTTP/JSON
┌──────────▼──────────┐
│  FastAPI Backend    │
│  - File Processing  │
│  - Vectorization    │
│  - Query Handling   │
└──────────┬──────────┘
           │
┌──────────┼──────────┐
│          │          │
│   ┌──────▼──┐   ┌───▼────────┐
│   │ LiteMAAS│   │   Qdrant   │
│   │- LLM In │   │- Vector DB │
│   │- Embed. │   │- Search    │
│   └─────────┘   └────────────┘
└─────────────────────────────────┘

🔌 Qdrant

  • All vector search and document chunk storage is powered by Qdrant
  • Qdrant runs as a container in the services section of each team compose file
  • You can inspect the live database at http://localhost:6333 (default admin interface)
  • Adapters for Qdrant are integrated in backend Python code via qdrant-client

🐧 Podman & Containerization

  • All builds use Containerfile (OCI-compatible, works seamlessly with Docker if needed)
  • Multi-container local dev and deployment is via podman-compose
  • OpenShift- and Kubernetes-ready by design
  • Vendor-neutral, dockerless container infrastructure

💡 Example Compose Section (team2/compose.yaml)

services:
  qdrant:
    image: qdrant/qdrant:v1.7.3
    ports:
      - 6333:6333
  
  backend:
    build: ./Backend
    depends_on:
      - qdrant
    environment:
      - QDRANT_HOST=qdrant
      - LITEMAAS_BASE_URL=http://litemaas:8000
  
  frontend:
    build: ./Frontend
    ports:
      - 8000:8000
    depends_on:
      - backend

🚀 Quick Start

Prerequisites

  • Docker & Docker Compose (or Podman & Podman Compose)
  • Python 3.11+ (for local development)
  • Node.js (optional, for development tools)

Development (Local)

  1. Clone and navigate to project:

    git clone <repo>
cd mentor-bot

  2. Create environment file:

    cp .env.example .env
# Edit .env with your configuration

  3. Install dependencies:

    pip install -r requirements.txt

  4. Start the server:

    python server.py

  5. Open browser:

    http://localhost:8000

Docker/Podman Deployment (Recommended)

  1. Build image:

    podman build -t mentor-bot:latest .

  2. Run with Compose:

    podman-compose up -d

  3. Access application:

    http://localhost:8000

  4. Access Qdrant interface:

    http://localhost:6333

Production (Traefik/OpenShift)

  1. Set environment variables:

    export TEAM_SUBDOMAIN=team1
export HOST_SUFFIX=192.168.1.100.sslip.io
export LITEMAAS_BASE_URL=http://litemaas:8000
export LITEMAAS_API_KEY=your-key
export QDRANT_HOST=qdrant

  2. Deploy with compose:

    podman-compose -f compose.yaml up -d

  3. Access via Traefik routing:

    http://team1.192.168.1.100.sslip.io

📁 Project Structure

mentor-bot/
├── index.html           # Main HTML page
├── styles.css          # Styling and layout
├── app.js              # Frontend application logic
├── server.py           # FastAPI backend server
├── requirements.txt    # Python dependencies
├── Containerfile       # Container image definition
├── compose.yaml        # Docker Compose configuration
├── .env.example        # Environment template
├── README.md           # This file
├── DEPLOYMENT.md       # Deployment documentation
├── DEVELOPMENT.md      # Development guide
└── GUIDE.md            # Team-specific information

🔧 Configuration

Environment Variables

Variable Description Default
LITEMAAS_BASE_URL LiteMAAS API endpoint http://litemaas:8000
LITEMAAS_API_KEY API authentication key dev-key
LITEMAAS_MODEL Model to use for inference Llama-4-Scout-17B
QDRANT_HOST Qdrant server host localhost
QDRANT_PORT Qdrant server port 6333
TEAM_SUBDOMAIN Traefik subdomain team1
HOST_SUFFIX Domain suffix (sslip.io) localhost
UPLOAD_DIR Directory for uploaded files /tmp/mentor_bot_uploads
PORT Server port 8000

Supported File Formats

  • PDF (.pdf) - Requires pdfplumber for full extraction
  • Markdown (.md) - Full support
  • Text (.txt) - Full support
  • Word (.docx) - Requires python-docx for full extraction

Maximum file size: 10MB

⚡ Workflow

  1. Upload files (PDF/TXT/MD/DOCX) from browser
  2. Files are split and embedded (Locally or via cloud LLM)
  3. Chunks stored & indexed in Qdrant
  4. User asks questions in chat interface
  5. Backend retrieves relevant chunks from Qdrant, sends to LiteMAAS
  6. LLM generates answer shown in UI

💻 Usage

Uploading Files

  1. Click the upload area or drag files
  2. Select supported file formats
  3. Wait for vectorization to complete
  4. View progress in the stats panel

Querying the Bot

  1. Type a question in the chat input
  2. Press Enter or click Send
  3. Bot searches vectorized documents in Qdrant
  4. Response based on relevant content + LiteMAAS inference

Managing Files

  • View all uploaded files in the sidebar
  • See file size, status, and chunk count
  • Remove files with the × button
  • Stats update automatically

🔌 API Endpoints

Health & Stats

GET /health
GET /api/stats

File Management

POST /api/upload
GET /api/files/{file_id}
DELETE /api/files/{file_id}

Query

POST /api/query
{
  "query": "How to contribute to open source?",
  "context": "Optional additional context"
}

🧠 Vectorization Process

  1. File Extraction: Text content extracted from uploaded file
  2. Chunking: Content split into overlapping ~512 character chunks
  3. Embedding: Each chunk converted to numerical vector via LiteMAAS or local model
  4. Storage: Chunks indexed in Qdrant vector database
  5. Search: Query matched against chunks using vector similarity scoring

Production Setup with Qdrant

The application uses Qdrant for scalable, high-performance vector storage:

  • Cosine similarity on embeddings
  • Persistent vector database
  • REST API for query operations
  • Real embedding models via LiteMAAS or specialized services

🔄 Integration with LiteMAAS

The bot integrates with LiteMAAS for:

  1. LLM Inference: Generate responses based on context
  2. Embeddings: Generate numerical vectors for semantic search
  3. Model Selection: Switch between available models (e.g., Llama-4-Scout-17B)

Fallback Behavior:

  • If LiteMAAS unavailable: Uses local response generation
  • If embedding fails: Uses deterministic hash-based vectors
  • Graceful degradation ensures application stays functional

🎨 Frontend Features

Components

  • Header: Branding, theme toggle
  • Sidebar: File upload, document list, stats
  • Chat Area: Message display, input field
  • Theme Toggle: Light/Dark mode (persisted to localStorage)

Responsive Breakpoints

  • Desktop: Full sidebar + chat layout
  • Tablet: Flexible layout
  • Mobile: Stacked layout with scrolling

📊 Vectorization Stats

The stats panel shows:

  • Total Files: Number of uploaded documents
  • Documents: Processed documents
  • Total Chunks: Combined text chunks from all files stored in Qdrant

Example: 3 files → 4 documents (with redundancy) → 247 chunks

🧪 Testing

Manual Testing

  1. Upload a markdown file with documentation
  2. Ask questions about the content
  3. Verify responses use uploaded documents
  4. Test file deletion
  5. Toggle dark mode
  6. Test on mobile

API Testing

# Upload file
curl -X POST -F "file=@document.pdf" http://localhost:8000/api/upload

# Query
curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Tell me about open source"}'

# Get stats
curl http://localhost:8000/api/stats

# Check Qdrant
curl http://localhost:6333/health

🚨 Error Handling

  • File too large: Shows error, doesn't upload
  • Unsupported format: Rejects with helpful message
  • API unavailable: Falls back to local responses
  • No documents: Prompts user to upload files
  • Qdrant unavailable: Returns error with helpful troubleshooting steps

All errors logged to server console for debugging.

🔐 Security Considerations

Current Implementation (Development)

  • ⚠️ No authentication
  • ⚠️ No input validation
  • ⚠️ In-memory storage (lost on restart)
  • ⚠️ Qdrant accessed without credentials (development mode)

Production Recommendations

  • Add authentication (OAuth, API keys)
  • Validate file content, not just extension
  • Use persistent database (PostgreSQL + vector extension)
  • Enable Qdrant API key authentication
  • Implement rate limiting
  • Sanitize LLM inputs
  • Add audit logging
  • Use HTTPS/TLS
  • Containerize with read-only root filesystem

📚 Further Development

Enhancements

  • Advanced vector database configuration
  • Advanced RAG (Retrieval-Augmented Generation)
  • Multi-language support
  • User authentication & file permissions
  • File preview in UI
  • Streaming responses
  • Export chat history
  • Admin dashboard with Qdrant metrics

Deployment

  • Kubernetes manifests
  • OpenShift deployment templates
  • GitOps integration (ArgoCD)
  • CI/CD pipeline (GitHub Actions)
  • Helm charts for Qdrant + Backend

🤝 Contributing

To contribute improvements:

  1. Make changes in isolated branch
  2. Document your changes
  3. Test locally with podman-compose
  4. Submit PR with description
  5. Follow Red Hat values principles

See CONTRIBUTING.md for detailed guidelines.

📁 File Locations

  • FastAPI backend: teams/team1/Backend/ or teams/team2/services/
  • Qdrant config: In compose.yaml under each team, and as qdrant service
  • Frontend: teams/team1/Frontend/ or teams/team2/static/
  • Compose, Containerfile: at team root

🎓 Red Hat Values in This Project

Open Collaboration

  • Source code publicly available
  • Clear architecture documentation
  • Template setup for team contributions
  • Encouraged to fork and modify

Transparency

  • Logging of all operations
  • Clear error messages
  • Stats visible to users
  • Architecture clearly documented

Community First

  • Helps beginners learn open source
  • Answers questions from uploaded docs
  • Encourages documentation sharing
  • Built for hackathon collaboration

Automation

  • Containerized deployment with Podman
  • Automated vectorization pipeline
  • Background file processing
  • Health checks built-in

Trust

  • Respects user uploads
  • No external data tracking
  • Clear data handling practices
  • Simple, auditable code

🆘 Troubleshooting

Application won't start

# Check logs
podman logs mentor-bot

# Verify port availability
lsof -i :8000

# Check environment variables
env | grep LITEMAAS
env | grep QDRANT

Qdrant not accessible

# Check if Qdrant container is running
podman ps | grep qdrant

# Check Qdrant logs
podman logs qdrant

# Verify port 6333 is accessible
curl http://localhost:6333/health

# Verify QDRANT_HOST environment variable
echo $QDRANT_HOST

Files not uploading

  • Check file size (max 10MB)
  • Verify file format (PDF, TXT, MD, DOCX)
  • Check disk space in UPLOAD_DIR
  • View browser console for errors
  • Verify Qdrant is running and accessible

Responses not generated

  • Verify LiteMAAS is running and accessible
  • Check LITEMAAS_API_KEY is correct
  • Verify Qdrant connection in server logs
  • Look for API errors in server logs
  • Try local response generation (disable API temporarily)

Performance issues

  • Reduce chunk size in config
  • Limit number of documents indexed
  • Increase Qdrant vector cache
  • Implement caching for frequent queries
  • Check Qdrant admin interface for optimization tips at http://localhost:6333

📞 Support

  • Check logs: podman logs mentor-bot
  • Review API endpoints: http://localhost:8000/docs (Swagger)
  • View Qdrant dashboard: http://localhost:6333
  • See configuration: Check .env file
  • Full documentation: See DEPLOYMENT.md, DEVELOPMENT.md, GUIDE.md
  • Red Hat documentation: Red Hat Knowledge Base

📑 License

GPL-3.0 (as per parent project)

🙏 Acknowledgments

  • Built for Red Hat Hackathon: "Open Source Mentor Bot"
  • Qdrant for blazing fast and scalable semantic search
  • Podman used for vendor-neutral, dockerless container infrastructure
  • LiteMAAS for LLM inference
  • Inspired by open collaboration and Red Hat values
  • Community contributions welcome!

Team repository structure has been modularized for multiple team experiments (teams/team1, teams/team2) — the team2 folder was used for our final pitch I, Mihael Atanasov, worked on a second autonomous approach (team1) for my personal learning effect. --> NOT FULLY FUNCTIONAL ANYMORE

About

AI-powered open-source Mentor bot built during the Red Hat Hackathon in Switzerland. Check out linkedin.com/in/atanasovmi for more!

Resources

Readme
GPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages