MedicBot

An agentic medical information assistant with RAG, tool calling, safety guardrails, and a live reasoning trace — built from scratch to understand how all the pieces actually fit together.

---

What it is

MedicBot is a conversational agent that answers medical questions using a combination of retrieval-augmented generation (RAG) over a curated knowledge base, autonomous tool calling (arithmetic, BMI, document search), and a multi-step safety pipeline. The whole thing runs behind a FastAPI backend with a custom web frontend.

The part I cared about most was making the agent's decision-making visible. There's a live "Agent Trace" panel on the right side of the UI that shows exactly what happened at each step — which tool was selected, what the retrieval returned, whether the answer passed the grounding check. No black boxes.

---

Features

• Tool calling: The agent decides on its own when to use calculate(), calculate_bmi(), search_medical_knowledge(), or search_document() — it's not hardcoded routing, the model picks based on the query.
• Dual-collection RAG: Two separate ChromaDB collections — one for the curated medical docs I wrote, one for whatever document the user uploads mid-session. The agent can distinguish between "general medical info" and "the file you just gave me."
• Safety classification: Every incoming message gets classified as SAFE, NEEDS_DISCLAIMER, or HIGH_RISK before the agent touches it. HIGH_RISK queries (dosage requests, self-diagnosis, emergencies) get blocked with a redirect to professional help.
• Evidence verification: After the agent generates an answer from retrieved chunks, a separate grounding check confirms whether the response actually sticks to the evidence or added unsupported claims.
• Formatted responses: Bot replies render full Markdown — section headers, bullet lists, bold labels, dividers, tables, code blocks — using marked.js with custom CSS typography.
• Multi-turn memory: Conversation history persists across turns with automatic trimming so context doesn't blow up.
• Live agent trace: Real-time sidebar showing safety classification, tool selection, retrieval results, and verification status for every query.

---

Tech stack

Component	What	Why
Language model	Gemini API via google-genai	Free tier, proper function calling support
Embeddings	sentence-transformers (all-MiniLM-L6-v2)	Runs locally, no extra API key needed
Vector store	ChromaDB	Local, persistent, zero config
Backend	FastAPI + Uvicorn	Straightforward REST API
Frontend	Vanilla HTML/CSS/JS + marked.js	Full control over the trace panel UI
Package manager	uv	Fast, no pip headaches

---

Project structure

MedicBot/
├── data/
│   └── medical_docs/           # curated condition summaries
│       ├── anemia.txt
│       ├── diabetes_type2.txt
│       ├── hypertension.txt
│       ├── migraine.txt
│       └── common_cold.txt
├── src/
│   ├── medicbot/
│   │   ├── agent.py            # core agent loop, tool dispatch
│   │   ├── api.py              # FastAPI routes
│   │   ├── llm.py              # Gemini client setup
│   │   ├── main.py             # CLI entry point
│   │   ├── rag.py              # chunking, embedding, ChromaDB
│   │   ├── safety.py           # query safety classifier
│   │   ├── tools.py            # calculator, BMI, search wrappers
│   │   ├── verification.py     # post-generation grounding check
│   │   └── static/
│   │       ├── index.html
│   │       ├── style.css
│   │       ├── app.js
│   │       └── marked.min.js
│   └── tests/
│       ├── test_memory.py
│       ├── test_rag.py
│       └── test_tools.py
├── .env
├── pyproject.toml
└── README.md

---

Getting started

Requirements: Python >= 3.14, uv

git clone https://github.com/Gyan-max/MedicBot.git
cd MedicBot

Create a .env file (or copy the example) and add your Gemini API key:

GEMINI_API_KEY=your_key_here

Install dependencies:

uv sync

---

Running it

Web UI (recommended):

uv run uvicorn src.medicbot.api:app --host 127.0.0.1 --port 8000

Then open http://127.0.0.1:8000 in your browser.

CLI mode:

uv run medicbot

---

Deploying on Render / Production

When deploying to Render or similar cloud providers, set the following:

• Build Command: pip install -r requirements.txt (or pip install -e .)
• Start Command: uvicorn medicbot.api:app --app-dir src --host 0.0.0.0 --port $PORT

(Alternatively, Render will automatically detect render.yaml if connected via Blueprint).

---

API

Method	Endpoint	What it does
POST	/api/chat	Send { "message": "..." }, get back { "answer": "...", "trace": [...] }
POST	/api/upload	Upload a .txt file (multipart form), returns chunk count
POST	/api/reset	Wipe agent memory and uploaded docs for a fresh session
GET	/	Serves the web UI

---

Tests

uv run pytest

---

Disclaimer

MedicBot is a learning project. It provides general health information for educational purposes only — it is not a diagnostic tool, and it is not a substitute for professional medical advice. If you have a medical concern, talk to a doctor.