| title | VERA Clinical Intelligence Platform |
|---|---|
| colorFrom | blue |
| colorTo | indigo |
| sdk | gradio |
| app_file | app.py |
| pinned | false |
VERA is an evidence-grounded Clinical Decision Support (CDS) Retrieval-Augmented Generation (RAG) platform designed for medical practitioners, geneticists, and clinical researchers.
The platform synthesizes clinical recommendations strictly from verified medical guidelines, peer-reviewed literature, and genomic datasets with verified in-line citations ([Document Name | Page Number]), verifiable safety guardrails, and dynamic BYOK (Bring Your Own Key) LLM integration.
- Strict Evidence Grounding: Enforces factual grounding against verified clinical literature, preventing ungrounded claims and hallucinations.
- Hybrid Retrieval Architecture: Combines semantic dense vector search (
ChromaDB+BAAI/bge-small-en-v1.5) with lexicalBM25retrieval and Reciprocal Rank Fusion (RRF). - Safety Confidence Gating: Automatically evaluates retrieval similarity scores prior to generation and blocks out-of-scope or unverified queries.
- Transparent Provenance: Every clinical recommendation links directly to its source document, clinical section, and exact page number.
- Dynamic BYOK Key Management: Supports runtime API key injection per request (Google Gemini and OpenAI), with automatic fallback to system defaults.
- AI Document Ingestion Guardrail: Automatically evaluates uploaded institutional PDF guidelines using smart profile sampling to prevent corrupt or non-medical indexing.
- Document-Scoped Chat: Allows targeting clinical inquiries to a specific document (
doc_id/doc_name) without cross-contamination. - Zero-Retention Session Processing: Processes uploaded guideline files in ephemeral memory, avoiding unauthorized permanent disk persistence.
- Multi-Platform Interfaces: Production-ready FastAPI REST API integrated with a Flutter mobile/web client and a 24/7 Telegram bot webhook.
The query execution pipeline consists of four sequential stages:
+-------------------------------------------------------------------------+
| 1. PRE-RETRIEVAL & QUERY ANALYSIS |
| - Emergency Detection & Immediate Life-Safety Refusal |
| - Out-of-Scope Pre-Filtering (Non-medical, recipes, general chat) |
| - Clinical Intent Extraction (Dosing, Diagnosis, Eligibility) |
+------------------------------------+------------------------------------+
|
v
+-------------------------------------------------------------------------+
| 2. HYBRID EVIDENCE RETRIEVAL |
| - Dense Vector Search (ChromaDB + bge-small-en-v1.5, 384 dimensions) |
| - Sparse Lexical Search (Rank-BM25 on Clinical Tokenized Corpus) |
| - Reciprocal Rank Fusion (RRF, k=60) & Metadata Top-K Extraction |
+------------------------------------+------------------------------------+
|
v
+-------------------------------------------------------------------------+
| 3. SAFETY & VERIFICATION GATING |
| - Similarity Threshold Evaluation (Min Confidence Score >= 0.60) |
| - Insufficient Evidence Refusal with Zero-Hallucination Enforcement |
| - Dynamic Real-Time Grounded Confidence Scoring |
+------------------------------------+------------------------------------+
|
v
+-------------------------------------------------------------------------+
| 4. GROUNDED SYNTHESIS & ATTRIBUTION |
| - Context-Constrained LLM Generation (Gemini 3.1 Flash Lite / OpenAI)|
| - Citation Extraction & Page Linking ([Document.pdf#page=X]) |
| - Structured Bullet Formatting & Post-Generation Faithfulness Check |
+-------------------------------------------------------------------------+
.
|-- Dockerfile # Production container configuration
|-- README.md # Primary project documentation
|-- app.py # Hugging Face Gradio + FastAPI mount entrypoint
|-- config/ # Global system configuration and hyperparameters
| `-- config.yaml
|-- data/ # Guideline repository and processed catalogs
| |-- processed/
| | |-- chunk_catalog.json # Processed and deduplicated chunk catalog
| | `-- document_registry.json # Registered guideline metadata
| `-- raw_pdfs/ # Verified institutional PDF guidelines
|-- notebooks/ # Exploratory research and pipeline verification
|-- pytest.ini # Automated test configuration
|-- requirements.txt # Production and development dependencies
|-- run_server.py # Local FastAPI server entrypoint
|-- run_telegram_bot.py # Standalone Telegram long-polling runner
|-- src/ # Core platform source code
| |-- api/ # FastAPI routes, schemas, and orchestration
| |-- embeddings/ # Vector store manager and local embedding model
| |-- evaluation/ # Benchmark suites and evaluation metrics
| |-- generation/ # LLM synthesis and citation formatters
| |-- ingestion/ # PDF extraction and section-aware chunking
| |-- retrieval/ # Hybrid search, BM25, and RRF fusion
| |-- safety/ # Refusal engine, confidence gates, and guardrails
| `-- utils/ # Structured logging and environment helpers
`-- tests/ # Comprehensive automated test suite
- Python 3.10 to 3.13
- Git
-
Clone the repository:
git clone https://github.com/AbdoTechno/vera.git cd vera -
Create and activate a virtual environment:
python -m venv venv # On Windows: .\venv\Scripts\activate # On Linux / macOS: source venv/bin/activate
-
Install dependencies:
pip install -r requirements.txt
-
Configure environment variables: Create a
.envfile in the root directory:GEMINI_API_KEY=your_google_gemini_api_key_here DEFAULT_LLM_PROVIDER=gemini DEFAULT_LLM_MODEL=models/gemini-3.1-flash-lite CONFIDENCE_THRESHOLD=0.60
Start the FastAPI application locally:
# Option 1: Using the runner script
python run_server.py
# Option 2: Using Uvicorn directly
uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reloadOnce running:
- Interactive Swagger UI: http://localhost:8000/docs
- Alternative ReDoc: http://localhost:8000/redoc
- Health Check Endpoint: http://localhost:8000/api/v1/health
POST /api/v1/chat
Processes clinical inquiries, executes hybrid retrieval and safety verification, and returns structured recommendations with verified citations.
Request Body:
{
"query": "What are the recommended loading doses for Nusinersen in SMA?",
"language": "en",
"provider": "gemini",
"doctor_context": {
"specialty": "Pediatric Neurology",
"experience_level": "Consultant",
"notes": "Evaluating loading schedule"
},
"doc_id": null
}Response Body (ChatResponse JSON):
{
"status": "success",
"language": "en",
"doctor_context": {
"specialty": "Pediatric Neurology",
"experience_level": "Consultant",
"notes": "Evaluating loading schedule"
},
"rag_pipeline_simulation": {
"step_1_query_analysis": {
"original_query": "What are the recommended loading doses for Nusinersen in SMA?",
"disease_category": "Spinal Muscular Atrophy (SMA)",
"intent": "Therapeutic Dosing & Protocol",
"status": "Completed"
},
"step_2_retrieval": {
"search_type": "Hybrid (Dense Vector + BM25 Lexical)",
"retrieved_count": 4,
"sources_found": [
{
"doc_id": "DOC_001",
"doc_title": "Spinal Muscular Atrophy: Update in Best Practices Recommendations for Treatment Considerations",
"journal": "Clinical Pediatrics",
"page_number": 4,
"section": "Dosing and Administration",
"similarity_score": 0.95,
"doclink": "ClinPediatr_2023_SMA_Treatment_Best_Practices.pdf#page=4"
}
]
},
"step_3_safety_and_verification": {
"confidence_score": 0.95,
"passed_safety_gate": true,
"hallucination_check": "Verified against retrieved clinical guidelines",
"status": "Safe & Grounded"
},
"step_4_synthesis": {
"model_used": "Gemini (models/gemini-3.1-flash-lite)",
"latency_seconds": 0.42,
"status": "Generated"
}
},
"clinical_response": {
"summary": "Clinical guidelines recommend initiating Nusinersen (Spinraza) with a structured loading regimen followed by regular maintenance doses administered via intrathecal injection.",
"detailed_recommendations": [
"Loading Phase: Administer 4 loading doses (12 mg / 5 mL each). The first 3 doses are given on Days 0, 14, and 28, followed by the 4th dose on Day 63 [ClinPediatr_2023_SMA_Treatment_Best_Practices.pdf#page=4].",
"Maintenance Phase: Administer maintenance doses of 12 mg once every 4 months thereafter [ClinPediatr_2023_SMA_Treatment_Best_Practices.pdf#page=4].",
"Pre-Treatment Monitoring: Conduct baseline laboratory evaluation including platelet counts, coagulation profile, and quantitative spot urine protein testing prior to each intrathecal administration."
],
"citations": [
{
"citation_id": 1,
"source": "Spinal Muscular Atrophy: Update in Best Practices Recommendations for Treatment Considerations",
"page": 4,
"section": "Dosing and Administration",
"doclink": "ClinPediatr_2023_SMA_Treatment_Best_Practices.pdf#page=4"
}
],
"medical_disclaimer": "VERA is an evidence-grounded research assistant designed for healthcare professionals and does not replace autonomous clinical diagnosis or medical practitioner judgment.",
"confidence_score": 0.95,
"confidence_percentage": "95%"
},
"available_medical_domains": {
"active": [
"Spinal Muscular Atrophy (SMA) Guidelines & Treatment",
"Clinical Cytogenetics & Chromosomal Rearrangements"
],
"upcoming_soon": [
"Pediatric Oncology Protocols",
"Cardiomyopathy & Heart Failure"
]
}
}POST /api/v1/upload-document
Validates an uploaded medical PDF using smart profile sampling and indexes its sections dynamically into the active vector catalog.
DELETE /api/v1/documents/{doc_id_or_filename}
Removes temporary session document vectors and catalog entries from active memory upon session completion.
POST /telegram/webhook
Handles incoming Telegram bot webhook updates, delivering structured cards with verified citations.
Run the automated test suite covering all platform layers:
pytest -vAll 19 test cases validate:
- In-line citation extraction and page linking
- Section-aware chunking boundaries
- Hybrid retrieval with Reciprocal Rank Fusion
- Emergency and out-of-scope safety gating
- Confidence gate rejection thresholds
- Telegram formatting and webhook handlers
VERA is designed as a research-grade clinical decision support assistant for licensed healthcare professionals. It does not replace independent clinical judgment or autonomous medical diagnosis.