README.md

metadata

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)

  {
    "query": "What are the early symptoms of lung cancer?",
    "session_id": "user_123_session_1699612345"
  }
  

• POST /ask/stream - Ask a question (streaming response)

  {
    "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:

git clone https://github.com/your-repo/lung-cancer-advisor.git
cd lung-cancer-advisor

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment variables:

cp .env.example .env
# Edit .env with your API keys

4. Run the application:

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)