Spaces:
Sleeping
Sleeping
| # Medical Q&A Bot - System Architecture | |
| ## Visual Overview | |
| ``` | |
| ┌─────────────────────────────────────────────────────────────────┐ | |
| │ USER INTERFACE │ | |
| │ │ | |
| │ ┌──────────────────────┐ ┌──────────────────────┐ │ | |
| │ │ Gradio Web UI │ │ Streamlit Web UI │ │ | |
| │ │ (app.py) │ OR │ (app_streamlit.py) │ │ | |
| │ │ Port: 7860 │ │ Port: 8501 │ │ | |
| │ └──────────┬───────────┘ └──────────┬───────────┘ │ | |
| └─────────────┼────────────────────────────────┼─────────────────┘ | |
| │ │ | |
| └────────────────┬───────────────┘ | |
| │ | |
| ▼ | |
| ┌────────────────────────────────┐ | |
| │ Query Processing Layer │ | |
| │ │ | |
| │ 1. Text Input Validation │ | |
| │ 2. Embedding Generation │ | |
| │ 3. Model Inference │ | |
| └────────────┬───────────────────┘ | |
| │ | |
| ▼ | |
| ┌────────────────────────────────┐ | |
| │ CLASSIFIER MODULE │ | |
| │ (classifier/) │ | |
| │ │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ SentenceTransformer │ │ | |
| │ │ Embedding Model │ │ | |
| │ └───────────┬──────────────┘ │ | |
| │ │ │ | |
| │ ▼ │ | |
| │ ┌──────────────────────────┐ │ | |
| │ │ Classification Head │ │ | |
| │ │ (Neural Network) │ │ | |
| │ └───────────┬──────────────┘ │ | |
| └──────────────┼─────────────────┘ | |
| │ | |
| ┌──────────┴──────────┐ | |
| │ │ | |
| ┌────────▼────────┐ ┌───────▼────────┐ | |
| │ MEDICAL │ │ ADMINISTRATIVE│ | |
| │ QUERY │ │ QUERY │ | |
| └────────┬────────┘ └───────┬────────┘ | |
| │ │ | |
| │ └──► End (No Retrieval) | |
| │ | |
| ▼ | |
| ┌─────────────────────────────────┐ | |
| │ RETRIEVAL MODULE │ | |
| │ (retriever/) │ | |
| │ │ | |
| │ ┌────────────────────────┐ │ | |
| │ │ BM25 Search │ │ | |
| │ │ (Sparse Retrieval) │ │ | |
| │ └───────────┬────────────┘ │ | |
| │ │ │ | |
| │ ┌───────────▼────────────┐ │ | |
| │ │ Dense Search │ │ | |
| │ │ (Vector Similarity) │ │ | |
| │ └───────────┬────────────┘ │ | |
| │ │ │ | |
| │ ┌───────────▼────────────┐ │ | |
| │ │ RRF Fusion │ │ | |
| │ │ (Rank Combination) │ │ | |
| │ └───────────┬────────────┘ │ | |
| │ │ │ | |
| │ ┌───────────▼────────────┐ │ | |
| │ │ Optional Reranker │ │ | |
| │ │ (Cross-Encoder) │ │ | |
| │ └───────────┬────────────┘ │ | |
| └──────────────┼─────────────────┘ | |
| │ | |
| ▼ | |
| ┌───────────────────────┐ | |
| │ DATA SOURCES │ | |
| │ │ | |
| │ • PubMed Articles │ | |
| │ • Miriad Q&A │ | |
| │ • UniDoc Q&A │ | |
| │ │ | |
| │ (data/corpora/) │ | |
| └───────────┬───────────┘ | |
| │ | |
| ▼ | |
| ┌───────────────────────┐ | |
| │ RESULTS │ | |
| │ │ | |
| │ • Document Title │ | |
| │ • Text Content │ | |
| │ • Relevance Scores │ | |
| │ • Metadata │ | |
| └───────────┬───────────┘ | |
| │ | |
| ▼ | |
| ┌───────────────────────┐ | |
| │ UI DISPLAY │ | |
| │ │ | |
| │ • Formatted Cards │ | |
| │ • JSON View │ | |
| │ • Score Badges │ | |
| └───────────────────────┘ | |
| ``` | |
| ## Data Flow | |
| ### 1. User Input | |
| ``` | |
| User Types Query → Web Interface Captures Input → Sends to Backend | |
| ``` | |
| ### 2. Classification Phase | |
| ``` | |
| Query Text | |
| ↓ | |
| Sentence Transformer (Embedding) | |
| ↓ | |
| Classification Head (Neural Network) | |
| ↓ | |
| Output: [Medical | Administrative | Other] + Confidence Scores | |
| ``` | |
| ### 3. Retrieval Phase (Medical Queries Only) | |
| ``` | |
| Medical Query | |
| ↓ | |
| ┌────────────────────────┐ | |
| │ Parallel Retrieval │ | |
| │ ┌─────────────────┐ │ | |
| │ │ BM25 (Sparse) │ │ ← Top 100 docs | |
| │ └─────────────────┘ │ | |
| │ ┌─────────────────┐ │ | |
| │ │ Dense (Vector) │ │ ← Top 100 docs | |
| │ └─────────────────┘ │ | |
| └────────────────────────┘ | |
| ↓ | |
| RRF Fusion Algorithm | |
| ↓ | |
| Top K Candidates | |
| ↓ | |
| Optional: Cross-Encoder Reranking | |
| ↓ | |
| Final Top N Results | |
| ``` | |
| ## Technology Stack | |
| ### Frontend | |
| - **Gradio** - Primary UI framework | |
| - **Streamlit** - Alternative UI framework | |
| - **HTML/CSS** - Custom styling | |
| - **JavaScript** - Auto-generated by frameworks | |
| ### Backend | |
| - **Python 3.8+** - Core language | |
| - **PyTorch** - Deep learning framework | |
| - **Sentence-Transformers** - Embedding models | |
| - **scikit-learn** - ML utilities | |
| ### Search & Retrieval | |
| - **Rank-BM25** - Sparse retrieval | |
| - **FAISS** - Dense vector search | |
| - **Custom RRF** - Rank fusion | |
| - **Cross-Encoder** - Optional reranking | |
| ### Data | |
| - **PubMed** - Medical research articles | |
| - **Miriad** - Medical Q&A database | |
| - **UniDoc** - Unified document corpus | |
| - **JSONL** - Data storage format | |
| ## Component Interactions | |
| ### 1. Initialization | |
| ```python | |
| # Load models once at startup | |
| embedding_model, classifier = classifier_init() | |
| ``` | |
| ### 2. Classification | |
| ```python | |
| classification = predict_query( | |
| text=[query], | |
| embedding_model=embedding_model, | |
| classifier_head=classifier | |
| ) | |
| ``` | |
| ### 3. Retrieval | |
| ```python | |
| hits = get_candidates( | |
| query=query, | |
| k_retrieve=10, | |
| use_reranker=False | |
| ) | |
| ``` | |
| ### 4. Display | |
| ```python | |
| # Gradio displays results in tabs | |
| # - Formatted HTML view | |
| # - Raw JSON view | |
| ``` | |
| ## Performance Characteristics | |
| ### Speed | |
| - **Classification**: ~100-500ms | |
| - **BM25 Search**: ~50-200ms | |
| - **Dense Search**: ~100-300ms | |
| - **Reranking**: ~500-2000ms (if enabled) | |
| ### Accuracy | |
| - **Classification**: ~95% accuracy | |
| - **Retrieval**: Depends on corpus and query | |
| - **Reranking**: +5-10% improvement | |
| ### Resource Usage | |
| - **Memory**: ~2-4 GB (with models loaded) | |
| - **CPU**: Moderate during inference | |
| - **GPU**: Optional (speeds up inference) | |
| ## Scalability Considerations | |
| ### Current Setup (Single User) | |
| - ✅ Perfect for demos and development | |
| - ✅ Low latency | |
| - ✅ Easy to debug | |
| ### Future Scaling Options | |
| - 🔄 Add caching for common queries | |
| - 🔄 Deploy on cloud with autoscaling | |
| - 🔄 Use model quantization for faster inference | |
| - 🔄 Implement request queuing | |
| - 🔄 Add load balancing | |
| ## Security & Privacy | |
| ### Current Implementation | |
| - Local hosting only | |
| - No data persistence | |
| - No user tracking | |
| - No authentication (optional) | |
| ### Production Considerations | |
| - Add user authentication | |
| - Implement rate limiting | |
| - Sanitize inputs | |
| - Log access for auditing | |
| - HTTPS for encrypted communication | |
| ## Monitoring & Debugging | |
| ### Available Information | |
| - Query classification results | |
| - Confidence scores per category | |
| - Retrieval scores (BM25, Dense, RRF) | |
| - Document metadata | |
| - Error messages | |
| ### Debug Mode | |
| ```python | |
| # In app.py, set: | |
| demo.launch(show_error=True) # Shows detailed errors | |
| ``` | |
| ## Deployment Options | |
| ### 1. Local (Current) | |
| ``` | |
| Pros: Easy, fast, secure | |
| Cons: Single user, not accessible remotely | |
| ``` | |
| ### 2. Hugging Face Spaces | |
| ``` | |
| Pros: Free, easy deploy, public URL | |
| Cons: Limited resources, public access | |
| ``` | |
| ### 3. Cloud (AWS/GCP/Azure) | |
| ``` | |
| Pros: Scalable, private, customizable | |
| Cons: Costs money, requires setup | |
| ``` | |
| ### 4. Docker Container | |
| ``` | |
| Pros: Portable, consistent environment | |
| Cons: Requires Docker knowledge | |
| ``` | |
| ## File Structure | |
| ``` | |
| health-query-classifier/ | |
| ├── 🖥️ UI Layer | |
| │ ├── app.py # Main Gradio UI | |
| │ ├── app_streamlit.py # Alternative Streamlit UI | |
| │ ├── launch_ui.bat # Windows launcher | |
| │ └── launch_ui.ps1 # PowerShell launcher | |
| │ | |
| ├── 🧠 Classifier Layer | |
| │ ├── classifier/ | |
| │ │ ├── infer.py # Inference logic | |
| │ │ ├── head.py # Classification head | |
| │ │ ├── train.py # Training script | |
| │ │ └── utils.py # Utilities | |
| │ | |
| ├── 🔍 Retrieval Layer | |
| │ ├── retriever/ | |
| │ │ ├── search.py # Search interface | |
| │ │ ├── index_bm25.py # BM25 indexing | |
| │ │ ├── index_dense.py # Dense indexing | |
| │ │ └── rrf.py # Rank fusion | |
| │ | |
| ├── 👥 Team Layer | |
| │ ├── team/ | |
| │ │ ├── candidates.py # Candidate retrieval | |
| │ │ └── interfaces.py # Data interfaces | |
| │ | |
| ├── 📊 Data Layer | |
| │ ├── data/ | |
| │ │ └── corpora/ # Corpus files | |
| │ │ ├── medical_qa.jsonl | |
| │ │ ├── miriad_text.jsonl | |
| │ │ └── unidoc_qa.jsonl | |
| │ | |
| └── 📚 Documentation | |
| ├── README.md # Main documentation | |
| ├── QUICKSTART.md # Quick start guide | |
| ├── UI_README.md # UI documentation | |
| ├── UI_IMPLEMENTATION.md # Implementation details | |
| └── ARCHITECTURE.md # This file | |
| ``` | |
| --- | |
| This architecture ensures: | |
| - ✅ Clean separation of concerns | |
| - ✅ Modular design | |
| - ✅ Easy to test and debug | |
| - ✅ Scalable and maintainable | |
| - ✅ Well-documented | |