README.md

metadata

title: Cybersecurity Panel
emoji: 🛡️
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false
app_port: 7860

Cybersecurity Panel

An AI-powered cybersecurity guidance system that provides expert advice through a panel of specialized advisor personas. Ask about threats, compliance, incident response, architecture, and career growth and get diverse perspectives from multiple AI advisors. Built on Neon AI's Collaborative Conversational AI (CCAI) framework.

Hugging Face Spaces deployment

This Space ships as a single Docker image built from the repository root Dockerfile. The container does three things:

1. Builds the React frontend (CRA) at image-build time with REACT_APP_API_URL="" so every fetch issues a relative URL.
2. Serves the bundled SPA from FastAPI at /, with the API exposed on /api/..., /auth/..., etc., on the same :7860 origin.
3. Persists user data (auth, profiles, chat sessions, onboarding, canvas state) in SQLite via aiosqlite at ${DATA_DIR}/cybersecurity_panel.db. Mount a Hugging Face Storage Bucket at /data to make the database survive Space rebuilds — there is no MongoDB, no Atlas, no third-party data plane (the persistence pattern follows CU-Student-AIProject-Helper).

Required Space secrets

Secret	Purpose
JWT_SECRET_KEY	Signs auth tokens. Set this to a long random string.
GEMINI_API_KEY	Powers the default Gemini provider (model: gemini-2.5-flash).
OPENAI_API_KEY	Optional — only required if you switch to the OpenAI provider.
VLLM_API_KEY	Optional — only required if you point the orchestrator/advisors at a Neon vLLM endpoint.

Features

• Multiple AI Advisor Personas: Chat with 10+ specialized advisors including Methodologist, Theorist, Pragmatist, and more
• Document Upload & Analysis: Upload PDFs, Word documents, and text files for context-aware advice
• Intelligent Document Retrieval (RAG): Advanced semantic search through your uploaded documents
• Multi-LLM Backend: Supports both Gemini API and local Ollama models
• User Authentication: Secure user accounts with persistent chat sessions
• Chat Session Management: Save, load, and manage multiple conversation threads
• Export Capabilities: Export chats and summaries in TXT, PDF, and DOCX formats
• Real-time Chat Interface: Modern, responsive UI with advisor-specific styling

Architecture

Frontend (React)

• Technology: React 18 with modern hooks and functional components
• Styling: CSS custom properties with dark/light theme support
• State Management: React Context and hooks
• Authentication: JWT-based authentication with persistent sessions

Backend (FastAPI)

• Framework: FastAPI with automatic API documentation
• Database: MongoDB for user data and chat sessions
• Vector Database: ChromaDB for document storage and semantic search
• LLM Integration: Support for Gemini API and Ollama models
• Document Processing: PDF, DOCX, and text file extraction with intelligent chunking
• Authentication: JWT tokens with bcrypt password hashing

Quick Start (Docker)

Prerequisites

• Docker

Instructions

1. Clone the repository

git clone https://github.com/NeonGeckoCom/CCAI-Demo.git
cd CCAI-Demo

1. Configure via .env file Create a .env file in the root of the project with:

GEMINI_API_KEY=<valid Gemini API key>
JWT_SECRET_KEY=<Generated UUID>
REACT_APP_API_URL=http://localhost:8000
CORS_ORIGINS=http://localhost:3000

REACT_APP_API_URL and CORS_ORIGINS must match the real addresses used if accessing the demo from a remote host.

2. Build and Run Containers

docker compose up -d

3. Access the application
   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000

Local Installation Prerequisites

• Python 3.8+ (3.9+ recommended)
• Node.js 16+ and npm
• MongoDB (Community Edition)
• Git

Installation Guide

Step 1: Clone the Repository

git clone https://github.com/NeonGeckoCom/CCAI-Demo.git
cd CCAI-Demo

Step 2: MongoDB Setup

Option A: Local MongoDB Installation

On Windows:

1. Download MongoDB Community Server from mongodb.com
2. Install with default settings
3. MongoDB will run as a Windows Service automatically

On macOS:

# Using Homebrew
brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb/brew/mongodb-community

On Linux (Ubuntu/Debian):

# Import MongoDB public GPG key
wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -

# Create list file
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

# Install MongoDB
sudo apt-get update
sudo apt-get install -y mongodb-org

# Start MongoDB
sudo systemctl start mongod
sudo systemctl enable mongod

Option B: MongoDB Atlas (Cloud)

1. Create a free account at MongoDB Atlas
2. Create a new cluster
3. Get your connection string
4. Skip the local MongoDB setup

Step 3: Ollama Installation (for Local LLM Support)

Install Ollama

On Windows:

1. Download Ollama from ollama.ai
2. Run the installer
3. Ollama will start automatically

On macOS:

# Using Homebrew
brew install ollama

# Or download from ollama.ai

On Linux:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
sudo systemctl start ollama
sudo systemctl enable ollama

Download Required Models

Once Ollama is installed, download the recommended models:

# Download the default model (recommended for development)
ollama pull llama3.2:1b

# Optional: Download larger, more capable models
ollama pull llama3.2:3b
ollama pull mistral:7b

# Verify installation
ollama list

Note: The llama3.2:1b model is small (~1.3GB) and fast, perfect for development. For production, consider larger models for better quality.

Step 4: Backend Setup

1. Navigate to the backend directory:

cd multi_llm_chatbot_backend

2. Create a Python virtual environment:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

3. Install Python dependencies:

pip install -r requirements.txt

4. Set up environment variables: Create a .env file in the multi_llm_chatbot_backend directory:

# MongoDB Configuration
MONGODB_CONNECTION_STRING=mongodb://localhost:27017
MONGODB_DATABASE_NAME=phd_advisor

# JWT Configuration
JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production-please-make-it-long-and-random

# Gemini API Configuration (Optional - for cloud LLM)
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.0-flash

# Ollama Configuration (for local LLM)
OLLAMA_BASE_URL=http://localhost:11434

# Application Settings
CORS_ORIGINS=http://localhost:3000

Getting a Gemini API Key (Optional):

1. Go to Google AI Studio

2. Create a new API key

3. Add it to your .env file

4. Start the backend server:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at http://localhost:8000 with interactive docs at http://localhost:8000/docs

Step 5: Frontend Setup

1. Navigate to the frontend directory:

cd ../phd-advisor-frontend

2. Install dependencies:

npm install

3. Start the development server:

npm start

The application will open at http://localhost:3000

Quick Start Guide

First Time Setup Checklist

1. MongoDB is running (check with mongosh or MongoDB Compass)
2. Ollama is running with models downloaded (ollama list)
3. Backend is running on port 8000
4. Frontend is running on port 3000
5. Create your first user account

Basic Usage

1. Create an Account:

   • Open http://localhost:3000
   • Click "Sign Up"
   • Fill in your details

2. Start Your First Chat:

   • Click "New Chat"
   • Ask a question like "I need help with my research methodology"
   • Get responses from multiple advisor personas

3. Upload Documents:

   • Click the upload button in the chat
   • Upload a PDF, DOCX, or TXT file
   • Ask questions about your document

4. Manage Chats:

   • Save important conversations
   • Switch between different chat sessions
   • Export chats in various formats

🔧 Configuration

Environment Variables Reference

Variable	Description	Default	Required
MONGODB_CONNECTION_STRING	MongoDB connection URL	mongodb://localhost:27017	Yes
MONGODB_DATABASE_NAME	Database name	phd_advisor	Yes
JWT_SECRET_KEY	Secret key for JWT tokens	-	Yes
GEMINI_API_KEY	Google Gemini API key	-	No
GEMINI_MODEL	Gemini model to use	gemini-2.0-flash	No
OLLAMA_BASE_URL	Ollama server URL	http://localhost:11434	No

Switching Between LLM Providers

The application supports two LLM providers:

1. Ollama (Local, Free):

   • Ensure Ollama is running
   • Models run locally on your machine
   • No API costs, complete privacy

2. Gemini (Cloud, Paid):

   • Requires API key
   • Higher quality responses
   • Faster response times

Switch providers using the API:

curl -X POST "http://localhost:8000/switch-provider" \
  -H "Content-Type: application/json" \
  -d '{"provider": "ollama"}'

API Documentation

Authentication Endpoints

• POST /auth/signup - Create new user account
• POST /auth/login - Login with email/password
• GET /auth/me - Get current user profile

Chat Endpoints

• POST /chat-stream - Get streaming responses from all advisors (NDJSON)
• POST /chat/{persona_id} - Chat with specific advisor
• POST /reply-to-advisor - Reply to specific advisor message

Document Management

• POST /upload-document - Upload PDF, DOCX, or TXT files
• GET /uploaded-files - List uploaded files
• GET /document-stats - Get document statistics

Session Management

• GET /context - Get current session context
• POST /reset-session - Reset current session
• GET /session-stats - Get session statistics

Export & Summary

• GET /export-chat - Export chat (txt, pdf, docx)
• GET /chat-summary - Generate chat summary

Full API documentation is available at http://localhost:8000/docs when the server is running.

Troubleshooting

Common Issues

Backend won't start:

# Check if port 8000 is already in use
netstat -an | grep :8000

# Check Python virtual environment is activated
which python  # Should point to your venv

# Check all dependencies are installed
pip list

MongoDB connection issues:

# Test MongoDB connection
mongosh

# Check if MongoDB service is running
# Windows: Check Services app
# macOS: brew services list | grep mongodb
# Linux: systemctl status mongod

Ollama not working:

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Check downloaded models
ollama list

# Test model directly
ollama run llama3.2:1b "Hello"

Frontend won't connect to backend:

• Verify backend is running on port 8000
• Check CORS settings in backend .env
• Check browser developer console for errors

Performance Tips

1. For faster local LLM responses:

   • Use smaller models like llama3.2:1b for development
   • Ensure sufficient RAM (8GB+ recommended)
   • Use SSD storage for better model loading

2. For better document search:

   • Upload focused, relevant documents
   • Use clear, descriptive filenames
   • Break large documents into smaller sections

3. For production deployment:

   • Use larger, more capable models
   • Consider GPU acceleration for Ollama
   • Use MongoDB Atlas for cloud database
   • Set up proper authentication and HTTPS

Development

Running Tests

# Backend tests
cd multi_llm_chatbot_backend
python -m pytest app/tests/

# Test specific functionality
python app/tests/test_rag_system.py
python app/tests/debug_rag.py

Project Structure

phd-advisor-panel/
├── multi_llm_chatbot_backend/
│   ├── app/
│   │   ├── api/routes/          # API route handlers
│   │   ├── core/                # Core business logic
│   │   ├── llm/                 # LLM client implementations
│   │   ├── models/              # Data models and schemas
│   │   ├── utils/               # Utility functions
│   │   └── tests/               # Test files
│   ├── requirements.txt
│   └── .env
├── phd-advisor-frontend/
│   ├── src/
│   │   ├── components/          # React components
│   │   ├── pages/               # Page components
│   │   ├── styles/              # CSS files
│   │   └── utils/               # Frontend utilities
│   ├── package.json
│   └── public/
└── README.md

Adding New Advisor Personas

1. Edit app/models/default_personas.py
2. Add your persona configuration
3. Restart the backend server
4. The new persona will be available in chat

Extending Document Support

1. Add new file type to app/utils/document_extractor.py
2. Update the upload endpoint in app/api/routes/documents.py
3. Test with sample files

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• Check the API Documentation
• Report bugs by opening an issue
• Request features by opening an issue
• Contact the development team

Acknowledgments

• Built with FastAPI and React
• Powered by Ollama for local LLM support
• Uses ChromaDB for vector storage
• Document processing with PyPDF2 and python-docx

Copyright

© 2025 University of Colorado Boulder. All rights reserved.

This project is developed and maintained by the University of Colorado Boulder for academic and research purposes.