bnewcomer/MediBot

<p align="center"> <img src="static/Medibot%20logo.png" width="320" alt="MediBot Logo"> </p>

<h1 align="center">MediBot</h1>

<p align="center"> Educational symptom exploration with Gradio, OpenAI, FAISS, and a lightweight ranking pipeline. </p>

<p align="center"> <em>Not a medical device. For educational use only. Do not use this app to rule out emergencies or replace a licensed clinician.</em> </p>

Overview

MediBot accepts symptom questions in plain language and can:

• —extract structured symptom context from user text
• —ask follow-up questions when the symptom signal is too weak or ambiguous
• —estimate urgency for recognized symptoms
• —rank possible conditions for educational review
• —explain named conditions and list precautions
• —add travel-aware handling for rare tropical diseases

The app is built around a small multi-step workflow in app.py:

• —ReActRouter builds a short plan for each turn
• —ClarificationAgent decides whether follow-up questions are needed
• —SymptomSeverityAgent scores urgency and handles red-flag escalation
• —DiseaseDiagnosisAgent maps symptoms, retrieves FAISS candidates, and scores them
• —description and precaution agents answer disease-specific questions

Repository Layout

MediBot/
|-- app.py
|-- data/
|-- diagnosis_engine/
|-- eval/
|-- scripts/
|-- static/
|-- tests/
`-- requirements.txt

Key directories:

• —data/: CSV datasets used by the app
• —diagnosis_engine/: FAISS retrieval, scoring, reranking, prevalence priors, and vocabulary mapping
• —eval/: deterministic real-query evaluation cases and runner
• —scripts/: lightweight local checks such as smoke_check.py
• —tests/: pytest coverage for helpers, chat flow, and realistic symptom queries

Local Setup

1. 1.Create and activate a virtual environment.
2. 2.Install runtime dependencies from requirements.txt.
3. 3.Install requirements-dev.txt as well if you want to run tests locally.
4. 4.Set OPENAI_API_KEY in your environment or a local .env file.
5. 5.Run the smoke check before launching the app.

Example:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
python scripts/smoke_check.py
python app.py

If you use make, the repo also includes MakeFile.mak with helper targets for setup, tests, and deployment checks.

Testing

Quick checks:

python scripts/smoke_check.py
python scripts/evaluate_real_queries.py

Pytest:

.venv\Scripts\python.exe -m pytest tests -q

Make targets:

make -f MakeFile.mak smoke-check
make -f MakeFile.mak eval
make -f MakeFile.mak test
make -f MakeFile.mak deploy-check

The real-query evaluation uses natural-language prompts from eval/real_symptom_queries.json and runs them through a deterministic fallback path so results stay stable across test runs.

Hugging Face Deployment

Before deploying to Hugging Face Spaces:

• —set OPENAI_API_KEY as a Space Secret
• —run python scripts/smoke_check.py
• —optionally run python scripts/evaluate_real_queries.py
• —confirm all required CSV files are present in data/
• —review logging behavior and avoid storing raw public symptom text

Do not commit or deploy local-only files:

• —.env
• —.env.*
• —logs/
• —faiss_store/
• —__pycache__/
• —*.pyc

These exclusions are also tracked in .hfignore.

Optional to exclude from Spaces if you do not need them there:

• —tests/
• —eval/

Notes on Ranking

The displayed "match strength" is the candidate hybrid_score. It combines:

• —Jaccard overlap
• —TF-IDF cosine similarity
• —symptom coverage
• —a rarity penalty derived from diagnosis_engine/prevalence.py

Weak matches are expected for broad symptom sets. The app explicitly warns users when the top score is low and asks follow-up questions when evidence is too ambiguous.

Related Docs

• —MediBot_Colab.ipynb
• —APP_FLOW.md
• —DEPLOYMENT.md
• —TRAVEL_PROMPT_FEATURE.md
• —TROPICAL_DISEASE_FIX.md
• —RARE_DISEASE_FIX.md
• —RARITY_SIMILARITY_FIX.md
• —CONTRIBUTING.md