README.md

---
title: Lung Cancer Clinical Decision Support System
emoji: 🫁
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860
---

# Lung Cancer Clinical Decision Support System

A specialized AI-powered clinical decision support system for thoracic oncologists, pulmonologists, and healthcare professionals managing lung cancer patients. Built with Retrieval-Augmented Generation (RAG) and agentic AI capabilities.

## 🎯 Features

### Core Capabilities
- **Specialized Knowledge**: Focused on NSCLC and SCLC management
- **Evidence-Based Guidance**: Retrieves information from authoritative medical guidelines (NCCN, ASCO, ESMO, NICE)
- **Molecular Testing**: EGFR, ALK, ROS1, BRAF, MET, RET, KRAS, PD-L1, TMB
- **Treatment Modalities**: Targeted therapy, immunotherapy, chemotherapy, radiation, surgery
- **Comprehensive Citations**: Inline citations with page references for every answer

### Technical Features
- **Hybrid Search**: Vector search (FAISS) + BM25 for optimal retrieval
- **Context Enrichment**: Automatically includes surrounding pages for complete clinical context
- **Streaming Responses**: Real-time answer generation
- **Session Management**: Conversation history tracking
- **Export Functionality**: Export conversations as PDF or DOCX
- **Authentication**: Secure session-based authentication
- **Rate Limiting**: Built-in API rate limiting

## 🚀 Deployment

### Live API
The API is deployed at: **https://moazx-lung-cancer-ai-advisor.hf.space**

### Quick Start

1. **Access the API**:
   - API Docs: https://moazx-lung-cancer-ai-advisor.hf.space/docs
   - Health Check: https://moazx-lung-cancer-ai-advisor.hf.space/health




## 📚 API Endpoints

### Health & Status
- `GET /` - API information
- `GET /health` - Health check
- `GET /health/initialization` - Initialization status

### Authentication
- `POST /auth/login` - User login
- `POST /auth/logout` - User logout
- `GET /auth/status` - Check authentication status
up
### Medical Queries
- `POST /ask` - Ask a question (complete response)
  ```json
  {
    "query": "What are the early symptoms of lung cancer?",
    "session_id": "user_123_session_1699612345"
  }
  ```
- `POST /ask/stream` - Ask a question (streaming response)
  ```json
  {
    "query": "What are the treatment options?",
    "session_id": "user_123_session_1699612345"
  }
  ```

### Export
- `GET /export/{format}?session_id={id}` - Export conversation (format: pdf, docx, txt)

## 💻 Local Development

### Prerequisites
- Python 3.11+
- OpenAI API key
- GitHub Personal Access Token (for side effects storage)

### Setup

1. **Clone the repository**:
```bash
git clone https://github.com/your-repo/lung-cancer-advisor.git
cd lung-cancer-advisor
```

2. **Install dependencies**:
```bash
pip install -r requirements.txt
```

3. **Configure environment variables**:
```bash
cp .env.example .env
# Edit .env with your API keys
```

4. **Run the application**:
```bash
python app.py
```

5. **Access the application**:
   - API: http://localhost:7860
   - Docs: http://localhost:7860/docs
   - Frontend: Open `frontend/index.html`

## 🔧 Configuration

### Environment Variables

See `.env.example` for all configuration options:

- `OPENAI_API_KEY`: Your OpenAI API key (required)
- `GITHUB_TOKEN`: GitHub token for side effects storage (optional)
- `PORT`: Server port (default: 7860)
- `ALLOWED_ORIGINS`: CORS allowed origins


## 🏗️ Architecture

### Components

- **FastAPI Backend**: RESTful API with async support
- **LangChain Agent**: Orchestrates tools and generates responses
- **Vector Store**: FAISS for semantic search
- **BM25 Search**: Keyword-based retrieval
- **Context Enrichment**: Adds surrounding pages for complete context
- **Frontend**: Vanilla JavaScript with Markdown rendering

### Agent Tools

1. **medical_guidelines_knowledge_tool**: Retrieves information from guidelines
2. **compare_providers_tool**: Compares guidance between providers
3. **side_effect_recording_tool**: Records adverse drug reactions
4. **get_current_datetime_tool**: Gets current date/time

## 📊 Response Format

The agent provides:
- **Concise, evidence-based answers** for busy clinicians
- **Inline citations** after each statement
- **Comprehensive reference list** at the end
- **Structured markdown formatting** for easy scanning
- **Real-time streaming** for immediate feedback

Example:
```
### First-Line Treatment for EGFR-Mutated NSCLC

**Recommended Options:**
- Osimertinib 80mg daily (Source: NCCN.pdf, Page: 45, Provider: NCCN)
- Alternative: Erlotinib or Gefitinib for exon 19 deletions (Page: 46)

**References:**
(Source: NCCN.pdf, Pages: 45, 46, Provider: NCCN, Location: NSCLC Treatment Algorithm)
```