README.md

---
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`](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`](https://github.com/NeonClary/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**
```bash
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**
```bash
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

```bash
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](https://www.mongodb.com/try/download/community)
2. Install with default settings
3. MongoDB will run as a Windows Service automatically

**On macOS:**
```bash
# Using Homebrew
brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb/brew/mongodb-community
```

**On Linux (Ubuntu/Debian):**
```bash
# 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](https://www.mongodb.com/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](https://ollama.ai)
2. Run the installer
3. Ollama will start automatically

**On macOS:**
```bash
# Using Homebrew
brew install ollama

# Or download from ollama.ai
```

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

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

2. **Create a Python virtual environment:**
```bash
# 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:**
```bash
pip install -r requirements.txt
```

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

```env
# 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](https://makersuite.google.com/app/apikey)
2. Create a new API key
3. Add it to your `.env` file

5. **Start the backend server:**
```bash
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:**
```bash
cd ../phd-advisor-frontend
```

2. **Install dependencies:**
```bash
npm install
```

3. **Start the development server:**
```bash
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:
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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

```bash
# 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](http://localhost:8000/docs)
- Report bugs by opening an issue
- Request features by opening an issue
- Contact the development team

## Acknowledgments

- Built with [FastAPI](https://fastapi.tiangolo.com/) and [React](https://reactjs.org/)
- Powered by [Ollama](https://ollama.ai/) for local LLM support
- Uses [ChromaDB](https://www.trychroma.com/) for vector storage
- Document processing with [PyPDF2](https://pypdf2.readthedocs.io/) and [python-docx](https://python-docx.readthedocs.io/)

## 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.