CHORE: Updated readme and setup guide

README.md

@@ -5,122 +5,56 @@ colorFrom: yellow
 colorTo: green
 sdk: docker
 pinned: false
-license: mit
-short_description: Group project for uni work
+license: apache-2.0
+short_description: University project creating an AI-powered medical system
 python_version: 3.11
 app_port: 7860
 ---
 
-# Medical AI Assistant
-
-AI-powered medical chatbot with patient-centric memory, MongoDB persistence, and a fast, modern UI.
-
-## 🚀 Key Features
-
-- Patient-centric RAG memory
-  - Short-term: last 3 QA summaries in in-memory LRU (fast context)
-  - Long-term: last 20 QA summaries per patient persisted in MongoDB (continuity)
-- Chat history persistence per session in MongoDB
-- Patient/Doctor context saved on all messages and summaries
-- Patient search typeahead (name or ID) with instant session hydration
-- Doctor dropdown with built‑in "Create doctor user..." flow
-- Modern UI: sidebar sessions, modals (doctor, settings, patient profile), dark/light mode, mobile-friendly
-- Model integration: Gemini responses, NVIDIA summariser fallback via key rotators
-
-## 🏗️ Architecture (high-level)
-
-### Medical Features
-- **Medical Knowledge Base**: Built-in medical information for common symptoms,
-conditions, and medications
-- **Context Awareness**: Remembers previous conversations and provides relevant medical
-context
-- **Role-Based Responses**: Tailored responses based on user's medical role and specialty
-- **Medical Disclaimers**: Appropriate warnings and disclaimers for medical information
-- **Export Functionality**: Export chat sessions for medical records or educational
-purposes
-
-Backend (FastAPI):
-- `src/core/memory/memory.py`: LRU short‑term memory + sessions
-- `src/core/memory/history.py`: builds context; writes memory/messages to Mongo
-- `src/data/`: Mongo helpers (modularized)
-  - `connection.py`: Mongo connection + collection names
-  - `session/operations.py`: chat sessions (ensure/list/delete/etc.)
-  - `message/operations.py`: chat messages (save/list)
-  - `patient/operations.py`: patients (get/create/update/search)
-  - `user/operations.py`: accounts/doctors (create/search/list)
-  - `medical/operations.py`: medical records + memory summaries
-  - `utils.py`: generic helpers (indexing, backups)
-- `src/api/routes/`: `chat`, `session`, `user` (patients), `system`, `static`
-
-Frontend (static):
-- `static/index.html`, `static/css/styles.css`
-- `static/js/app.js` (or modularized under `static/js/ui/*` and `static/js/chat/*` — see `UI_SETUP.md`)
-
-## 🛠️ Quick Start
-
-### Prerequisites
-- Python 3.11+
-- pip
-
-### Setup
-1. Clone and install
-```bash
-git clone https://huggingface.co/spaces/MedAI-COS30018/MedicalDiagnosisSystem
-cd MedAI
-pip install -r requirements.txt
-```
-2. Configure environment
-```bash
-# Create .env
-echo "GEMINI_API_1=your_gemini_api_key_1" > .env
-echo "NVIDIA_API_1=your_nvidia_api_key_1" >> .env
-# MongoDB (required)
-echo "MONGO_USER=your_mongodb_connection_string" >> .env
-# Optional DB name (default: medicaldiagnosissystem)
-# Optional DB name (default: medicaldiagnosissystem). Env var key: USER_DB
-echo "USER_DB=medicaldiagnosissystem" >> .env
-```
-3. Run
-```bash
-python -m src.main
-```
-Helpful: [UI SETUP](https://huggingface.co/spaces/MedAI-COS30018/MedicalDiagnosisSystem/blob/main/UI_SETUP.md) | [SETUP GUIDE](https://huggingface.co/spaces/MedAI-COS30018/MedicalDiagnosisSystem/blob/main/SETUP_GUIDE.md)
-
-## 🔧 Config
-- `GEMINI_API_1..5`, `NVIDIA_API_1..5`
-- `MONGO_USER`, `MONGO_DB`
-- `LOG_LEVEL`, `PORT`
-- Memory: 3 short‑term, 20 long‑term
-
-## 📱 Usage
-1. Select/create a doctor; set role/specialty.
-2. Search patient by name/ID; select a result.
-3. Start a new chat; ask your question.
-4. Manage sessions in the sidebar (rename/delete from menu).
-5. View patient profile and create/edit via modals/pages.
-
-## 🔌 Endpoints (selected)
-- `POST /chat` → `{ response, session_id, timestamp, medical_context? }`
-- `POST /sessions` → `{ session_id }`
-- `GET /patients/{patient_id}/sessions`
-- `GET /sessions/{session_id}/messages`
-- `DELETE /sessions/{session_id}` → deletes session (cache + Mongo) and its messages
-- `GET /patients/search?q=term&limit=8`
-
-## 🔒 Data & Privacy
-- MongoDB persistence keyed by `patient_id` with `doctor_id` attribution
-- UI localStorage for UX (doctor list, preferences, selected patient)
-- Avoid logging PHI; secure Mongo credentials
-
-## 🧪 Dev
-```bash
-pip install -r requirements.txt
-python -m src.main   # run
-pytest               # tests
-black . && flake8    # format + lint
-```
-
-## 🧾 License & Disclaimer
-- Apache 2.0 License (see [LICENSE](./LICENSE))
-- Educational information only; not a substitute for professional medical advice
-- Team D1 - COS30018, Swinburne University of Technology
+# Medical Diagnosis System
+
+An AI-powered medical chatbot designed for patient-centric interactions, featuring persistent memory and a modern, intuitive user interface. This system is containerised using Docker for simplified deployment and scalability.
+
+## System Architecture
+
+The application is comprised of a FastAPI backend and a static frontend, communicating via a RESTful API. The entire system is designed to be run within Docker containers, ensuring a consistent and reproducible environment.
+
+### Services and Technologies
+
+- **Backend**: Python 3.11 with FastAPI
+- **Database**: MongoDB for all persistent data, including user information, chat sessions, and long-term memory.
+- **AI Models**:
+	- **Primary**: Google's Gemini Pro for response generation.
+	- **Fallback**: An NVIDIA-based model for summarisation, accessed via a dedicated API.
+- **Containerisation**: Docker and Docker Compose for service orchestration.
+- **Frontend**: Static HTML, CSS, and vanilla JavaScript.
+
+### Retrieval-Augmented Generation (RAG) Implementation
+
+The system's contextual memory is built upon a RAG architecture to provide relevant and informed responses. This is achieved through a multi-layered memory system:
+
+- **Short-Term Memory**: An in-memory LRU (Least Recently Used) cache stores the summaries of the last three interactions. This allows for immediate context recall within an ongoing conversation.
+- **Long-Term Memory**: The summaries of the last twenty interactions for each patient are persisted in MongoDB. This provides a deeper historical context for recurring patients, allowing the system to reference past conversations and maintain continuity over time.
+
+When a query is received, the system retrieves the relevant short and long-term memory summaries to build a comprehensive context. This context is then provided to the Gemini model along with the user's query to generate an accurate and context-aware response.
+
+## Key Features
+
+- **Patient-Centric Memory**: Utilises both short-term and long-term memory to maintain context throughout conversations.
+- **Persistent Chat History**: All chat sessions are saved in MongoDB, allowing for a complete history of interactions.
+- **Contextual Awareness**: The system maintains the context of both the patient and the doctor in all messages and summaries.
+- **User Management**: Includes features for patient search (by name or ID) and a doctor dropdown with a streamlined user creation process.
+- **Modern User Interface**: The application features a sidebar for session management, modals for doctor and patient profiles, a dark/light mode, and a mobile-friendly design.
+- **AI Model Integration**: The system leverages Gemini for generating responses and includes a fallback to an NVIDIA summariser.
+
+## Getting Started
+
+To get the project up and running, please refer to the detailed instructions in the [setup guide](./SETUP_GUIDE.md).
+
+## Licence & Disclaimer
+
+This project is licensed under the Apache 2.0 Licence. See the [LICENCE](./LICENCE) file for details.
+
+The information provided by this system is for educational purposes only and is not a substitute for professional medical advice, diagnosis, or treatment. Always seek the advice of your physician or other qualified health provider with any questions you may have regarding a medical condition.
+
+Team D1 - COS30018, Swinburne University of Technology

SETUP_GUIDE.md

@@ -1,256 +1,147 @@
-# Medical AI Assistant - Setup Guide
+# Setup Guide
 
-## 🎯 What We've Built
+This guide provides instructions on how to set up and run the Medical Diagnosis System for both local development and using Docker.
 
-A comprehensive medical chatbot system with:
+## Prerequisites
 
-1. **ChatGPT-like UI** - Modern, responsive web interface
-2. **Multi-user Support** - Individual profiles and chat sessions
-3. **Medical Context Memory** - LRU-based memory system
-4. **API Key Rotation** - Dynamic Gemini API management
-5. **Fallback Systems** - Graceful degradation when services unavailable
+Before you begin, ensure you have the following installed:
 
-## 🚀 Quick Start
+- Git
+- Python 3.11 or higher
+- pip (Python package installer)
+- Docker and Docker Compose
 
-### 1. Install Dependencies
-```bash
-pip install -r requirements.txt
-```
+## Environment Variable Setup
 
-### 2. Set Environment Variables (Optional)
-```bash
-# For full Gemini AI functionality
-export GEMINI_API_1="your_api_key_1"
-export GEMINI_API_2="your_api_key_2"
-...
-export GEMINI_API_5="your_api_key_5"
-```
+The application is configured using a `.env` file in the project's root directory. This file is required for both local and Docker setups, but the values will differ.
 
-### 3. Start the System
-```bash
-python3 start.py
-```
+First, create the file:
 
-### 4. Access the UI
-Open your browser and go to: **http://localhost:8000**
-
-## 🏗️ System Architecture
-
-### Core Components
-- **`app.py`** - FastAPI main application with all endpoints
-- **`memo/memory.py`** - Enhanced LRU memory with user/session management
-- **`memo/history.py`** - Medical history manager with context awareness
-- **`utils/rotator.py`** - API key rotation for reliability
-- **`utils/embeddings.py`** - Embedding client with fallback support
-- **`static/`** - Complete web UI (HTML, CSS, JavaScript)
-
-### Key Features
-- **User Management**: Create profiles with medical roles and specialties
-- **Session Management**: Multiple concurrent chat sessions per user
-- **Medical Memory**: Context-aware responses using conversation history
-- **API Integration**: Gemini AI with automatic key rotation
-- **Responsive UI**: Works on desktop, tablet, and mobile
-
-## 📱 Using the System
-
-### First Time Setup
-1. **Access the UI** at http://localhost:8000
-2. **Click your profile** to set name, role, and specialty
-3. **Start a new chat** to begin your first conversation
-4. **Ask medical questions** in natural language
-
-### User Roles Available
-- **Physician** - Full medical context and clinical guidance
-- **Nurse** - Nursing-focused responses and care instructions
-- **Medical Student** - Educational content with learning objectives
-- **Healthcare Professional** - General medical information
-- **Patient** - Educational content with appropriate disclaimers
-
-### Features
-- **Real-time Chat**: Instant responses with typing indicators
-- **Session Export**: Download chat history as JSON files
-- **Context Memory**: System remembers previous conversations
-- **Medical Disclaimers**: Appropriate warnings for medical information
-- **Dark/Light Theme**: Automatic theme switching
-
-## 🔧 Configuration Options
-
-### Environment Variables
 ```bash
-# Required for full functionality
-GEMINI_API_1=your_key_1
-GEMINI_API_2=your_key_2
-GEMINI_API_3=your_key_3
-
-# Optional
-LOG_LEVEL=INFO
-PORT=8000
+touch .env
 ```
 
-### Memory Settings
-- **LRU Capacity**: 50 QA summaries per user (configurable)
-- **Max Sessions**: 20 sessions per user (configurable)
-- **Session Timeout**: Configurable session expiration
+Next, add the following variables to the file. Explanations for each setup type are provided below.
 
-### Embedding Model
-- **Default**: `all-MiniLM-L6-v2` (384 dimensions)
-- **Fallback**: Hash-based embeddings when model unavailable
-- **GPU Support**: Optional CUDA acceleration
+```ini
+# --- AI Model API Keys ---
+# Add at least one key for each service. The application will rotate through them.
+GEMINI_API_KEY_1=your_gemini_api_key
+NVIDIA_API_KEY_1=your_nvidia_api_key
 
-## 🧪 Testing the System
+# --- MongoDB Connection ---
+# Use the appropriate URI for your setup (see examples below)
+MONGO_URI=your_mongodb_connection_string
+DB_NAME=medicaldiagnosissystem
 
-### Run System Tests
-```bash
-python3 test_system.py
-```
-
-### Test Individual Components
-```bash
-# Test memory system
-python3 -c "from memo.memory import MemoryLRU; m = MemoryLRU(); print('✅ Memory system works')"
-
-# Test API rotator
-python3 -c "from utils.rotator import APIKeyRotator; r = APIKeyRotator('TEST_'); print('✅ Rotator works')"
-
-# Test embeddings
-python3 -c "from utils.embeddings import create_embedding_client; c = create_embedding_client(); print('✅ Embeddings work')"
+# --- Application Settings ---
+LOG_LEVEL=INFO
+PORT=7860
 ```
 
-## 🌐 API Endpoints
+### MongoDB URI Examples
 
-### Core Endpoints
-- **`GET /`** - Main web UI
-- **`POST /chat`** - Send chat messages
-- **`POST /users`** - Create user profiles
-- **`GET /users/{user_id}`** - Get user data and sessions
-- **`POST /sessions`** - Create chat sessions
-- **`GET /sessions/{session_id}`** - Get session details
-- **`DELETE /sessions/{session_id}`** - Delete sessions
+- **For Docker Setup (Recommended):** The `docker-compose.yml` file includes a MongoDB service. Use the following URI to connect the application container to the database container:
+	```ini
+	MONGO_URI=mongodb://root:example@mongo:27017/
+	```
 
-### Utility Endpoints
-- **`GET /health`** - System health check
-- **`GET /api/info`** - API information and capabilities
-- **`GET /docs`** - Interactive API documentation (Swagger UI)
+- **For Local Development:** You must run your own MongoDB instance. If it is running locally on the default port without authentication, your URI would be:
+	```ini
+	MONGO_URI=mongodb://localhost:27017/
+	```
 
-## 🔒 Security & Privacy
+## Docker Setup (Recommended)
 
-### Data Protection
-- **Local Storage**: User data stored in browser (no server persistence)
-- **Session Isolation**: Users can only access their own data
-- **No PII Storage**: Personal information not logged or stored
-- **Medical Disclaimers**: Clear warnings about information limitations
+This method runs the application and a MongoDB database in isolated containers, which is the quickest way to get started.
 
-### API Security
-- **Key Rotation**: Automatic API key rotation for security
-- **Rate Limiting**: Built-in protection against API abuse
-- **Error Handling**: Graceful degradation on API failures
+### 1. Configure Environment
+Ensure your `.env` file is present in the project root and contains the correct `MONGO_URI` for a Docker environment.
 
-## 🚀 Deployment
+### 2. Build and Run Containers
+From the project's root directory, run the following command. This will build the Docker images and start the application and database services.
 
-### Local Development
 ```bash
-python3 start.py
+docker-compose up --build
 ```
 
-### Production Deployment
-```bash
-# Set production environment variables
-export PRODUCTION=true
-export LOG_LEVEL=WARNING
+To run the containers in the background (detached mode), add the `-d` flag:
 
-# Start with production settings
-uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
+```bash
+docker-compose up --build -d
 ```
 
-### Docker Deployment
+The application will now be accessible at `http://localhost:7860`.
+
+### 3. Stopping the Application
+To stop and remove the containers, use:
 ```bash
-# Build and run with Docker
-docker build -t medical-ai-assistant .
-docker run -p 8000:8000 medical-ai-assistant
+docker-compose down
 ```
 
-## 🐛 Troubleshooting
+## Local Development Setup
 
-### Common Issues
+This method requires you to run a MongoDB instance on your local machine or have one accessible on your network.
 
-#### Import Errors
+### 1. Clone the Repository
 ```bash
-# Ensure you're in the right directory
+git clone https://github.com/COS30018-2025-Sem2-GroupD1/MedicalDiagnosisSystem.git
 cd MedicalDiagnosisSystem
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Check Python version (3.8+ required)
-python3 --version
 ```
 
-#### Port Already in Use
-```bash
-# Check what's using port 8000
-lsof -i :8000
+### 2. Configure Environment
+Ensure your `.env` file is present and contains the correct `MONGO_URI` that points to your externally-managed MongoDB instance.
 
-# Kill the process or use a different port
-export PORT=8001
-python3 start.py
-```
+### 3. Create and Activate a Virtual Environment
+It is highly recommended to use a virtual environment to isolate project dependencies.
 
-#### API Key Issues
+First, create the environment in the project's root directory:
 ```bash
-# Check environment variables
-echo $GEMINI_API_1
-
-# Set them if missing
-export GEMINI_API_1="your_key_here"
+python -m venv .venv
 ```
+Next, activate it. The command differs depending on your operating system:
 
-#### Memory Issues
-```bash
-# Check system resources
-free -h
-top
+- **On Linux or macOS:**
+	```bash
+	source .venv/bin/activate
+	```
 
-# Reduce memory usage in app.py
-# Set smaller capacity values in MemoryLRU
-```
+- **On Windows (using PowerShell):**
+	```powershell
+	.\.venv\Scripts\Activate.ps1
+	```
 
-### Getting Help
-- **Check logs**: Look for error messages in the console
-- **Test components**: Run `python3 test_system.py`
-- **Check health**: Visit http://localhost:8000/health
-- **API docs**: Visit http://localhost:8000/docs
+- **On Windows (using Command Prompt):**
+	```cmd
+	.\.venv\Scripts\activate.bat
+	```
 
-## 🔮 Future Enhancements
+Your shell prompt should now indicate that you are in the `.venv` environment.
 
-### Planned Features
-- **Database Integration**: Persistent storage for production use
-- **Advanced RAG**: Vector database for medical knowledge
-- **Multi-language Support**: Internationalization
-- **Voice Interface**: Speech-to-text and text-to-speech
-- **Mobile App**: Native iOS/Android applications
-- **Analytics Dashboard**: Usage statistics and insights
+### 4. Install Dependencies
+Install the required Python packages into your active virtual environment:
 
-### Customization
-- **Medical Knowledge Base**: Add your own medical content
-- **Response Templates**: Customize AI response styles
-- **Integration APIs**: Connect with existing medical systems
-- **Custom Models**: Use different AI models or fine-tuned versions
+```bash
+# Install all requirements for running
+pip install -r requirements.txt
 
-## 📚 Additional Resources
+# Install development-specific dependencies
+pip install -r requirements-dev.txt
+```
 
-### Documentation
-- **FastAPI**: https://fastapi.tiangolo.com/
-- **Uvicorn**: https://www.uvicorn.org/
-- **Google Gemini**: https://ai.google.dev/
-- **Sentence Transformers**: https://www.sbert.net/
+### 5. Run the Application
+To run the application for development, use `uvicorn`. This will start a local server that automatically reloads when you make code changes.
 
-### Support
-- **GitHub Issues**: Report bugs and request features
-- **Community**: Join discussions and share experiences
-- **Contributing**: Submit pull requests and improvements
+```bash
+uvicorn src.main:app --reload
+```
+The application will be accessible at `http://localhost:7860`.
 
----
+## Development Workflow
 
-**🎉 Your Medical AI Assistant is ready to use!**
+### Running Tests
+To run the test suite, use `pytest`:
 
-Start with `python3 start.py` and enjoy your intelligent medical chatbot!
+```bash
+pytest
+```