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-api.hf.space**

### Quick Start

1. **Access the API**:
   - API Docs: https://moazx-api.hf.space/docs
   - Health Check: https://moazx-api.hf.space/health

2. **Use the Frontend**:
   - Open `frontend/index.html` in a browser
   - Login with credentials (default: admin/admin123)
   - Start asking clinical questions

### Deploy Your Own Instance

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.

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

### Medical Queries
- `GET /ask?query={question}&session_id={id}` - Ask a question (non-streaming)
- `GET /ask/stream?query={question}&session_id={id}` - Ask a question (streaming)

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

### Authentication

Default credentials (change in production):
- Username: `admin`
- Password: `admin123`

Update in `api/routers/auth.py` or via environment variables.

## 📖 Usage Examples

### Using the API

```python
import requests

# Login
response = requests.post(
    "https://moazx-api.hf.space/auth/login",
    json={"username": "admin", "password": "admin123"}
)
cookies = response.cookies

# Ask a question
response = requests.get(
    "https://moazx-api.hf.space/ask",
    params={
        "query": "What is the first-line treatment for EGFR-mutated NSCLC?",
        "session_id": "my-session-123"
    },
    cookies=cookies
)
print(response.json()["response"])
```

### Using the Frontend

1. Open `frontend/index.html`
2. Login with credentials
3. Type your clinical question
4. Receive evidence-based answers with citations

## 🏗️ 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, targeted answers** for busy clinicians
- **Inline citations** after each statement
- **Comprehensive reference list** at the end
- **Structured formatting** for easy scanning

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)
```

## 🔒 Security

- Session-based authentication
- Rate limiting (100 requests/minute)
- CORS protection
- Input validation
- Secure cookie handling

## 📝 License

[Add your license here]

## 🤝 Contributing

Contributions are welcome! Please read the contributing guidelines first.

## 📧 Support

For issues or questions:
- Check the [DEPLOYMENT.md](DEPLOYMENT.md) guide
- Review API docs at `/docs`
- Open an issue on GitHub

## 🙏 Acknowledgments

Built with:
- FastAPI
- LangChain
- OpenAI
- FAISS
- Sentence Transformers