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

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

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

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 guide
• Review API docs at /docs
• Open an issue on GitHub

🙏 Acknowledgments

Built with:

• FastAPI
• LangChain
• OpenAI
• FAISS
• Sentence Transformers