whosouravsharma commited on
Commit
9c876ac
Β·
verified Β·
1 Parent(s): 4ba369d

Update README: system overview, models, data, API, limitations

Browse files
Files changed (1) hide show
  1. README.md +116 -10
README.md CHANGED
@@ -5,22 +5,128 @@ colorFrom: blue
5
  colorTo: purple
6
  sdk: docker
7
  app_port: 8501
 
8
  tags:
9
  - streamlit
 
 
 
 
 
 
 
 
10
  pinned: false
11
- short_description: RAG-grounded medical Q&A chat
12
  ---
13
 
14
  # Medical Assistant
15
 
16
- A chat UI that calls the `medical-assistant-ai-backend` Space's `POST /ask`
17
- endpoint, which runs a retrieval-augmented question-answering pipeline built
18
- on the MedQuAD dataset. Ask a medical question and get an answer grounded in
19
- retrieved source passages, with sources cited below each response.
20
 
21
- Requires two Space secrets/variables:
22
- - `BACKEND_URL` β€” the backend Space's URL (e.g.
23
- `https://whosouravsharma-medical-assistant-ai-backend.hf.space`)
24
- - `HF_TOKEN` β€” used to authenticate against the private backend Space
25
 
26
- Not a substitute for professional medical advice.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5
  colorTo: purple
6
  sdk: docker
7
  app_port: 8501
8
+ short_description: RAG-grounded medical Q&A chat over the MedQuAD dataset
9
  tags:
10
  - streamlit
11
+ - rag
12
+ - medical
13
+ - healthcare
14
+ - question-answering
15
+ - faiss
16
+ - sentence-transformers
17
+ models:
18
+ - sentence-transformers/all-MiniLM-L6-v2
19
  pinned: false
 
20
  ---
21
 
22
  # Medical Assistant
23
 
24
+ Ask a medical question and get an answer grounded in retrieved source
25
+ passages from the MedQuAD dataset, with the sources cited under every
26
+ response. The answer comes from retrieved text, not from the model's own
27
+ memory.
28
 
29
+ > **Not a substitute for professional medical advice, diagnosis, or treatment.**
 
 
 
30
 
31
+ This Space is the **frontend** of a two-Space system. Retrieval and
32
+ generation run in the
33
+ [`medical-assistant-ai-backend`](https://huggingface.co/spaces/whosouravsharma/medical-assistant-ai-backend)
34
+ Space.
35
+
36
+ ## How it works
37
+
38
+ 1. You type a question into the chat.
39
+ 2. This Space sends it to the backend's `POST /ask` endpoint.
40
+ 3. The backend embeds the question and retrieves the top 5 most similar
41
+ passages from a FAISS index built over MedQuAD.
42
+ 4. Those passages go into a prompt that tells the model to answer **only**
43
+ from the retrieved context, to avoid diagnosis and prescriptions, and to
44
+ say so when the context isn't enough to answer.
45
+ 5. A hosted LLM generates the answer, and the backend returns it along with
46
+ its sources.
47
+ 6. This Space shows the answer with the cited sources underneath.
48
+
49
+ ```
50
+ User ──▢ Streamlit UI (this Space) ──POST /ask──▢ FastAPI backend
51
+ β”‚
52
+ embed (MiniLM) ───
53
+ FAISS top-k ────── (MedQuAD index)
54
+ grounded prompt ──
55
+ hosted LLM β”€β”€β”€β”€β”€β”€β”˜
56
+ ◀──────────── answer + sources ────────────
57
+ ```
58
+
59
+ ## Components
60
+
61
+ | Component | Role |
62
+ |---|---|
63
+ | **This Space** (`Medical-Assistant-ChatBot`) | Streamlit chat UI. Its only dependencies are `streamlit` and `requests`, and it holds no model logic |
64
+ | [`medical-assistant-ai-backend`](https://huggingface.co/spaces/whosouravsharma/medical-assistant-ai-backend) | FastAPI service exposing `GET /health` and `POST /ask` |
65
+ | `whosouravsharma/medical-assistant-data` (private) | Prebuilt FAISS index and chunk metadata, pulled by the backend at startup |
66
+ | [MedQuAD](https://www.kaggle.com/datasets/pythonafroz/medquad-medical-question-answer-for-ai-research) | Source corpus of medical question–answer pairs |
67
+
68
+ ## Models
69
+
70
+ No model in this project is trained or fine-tuned. The system is built from
71
+ off-the-shelf components:
72
+
73
+ | Stage | Model / method | Notes |
74
+ |---|---|---|
75
+ | Embedding | [`sentence-transformers/all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) | Small (~90 MB), CPU-friendly, used unmodified. Loaded once per backend process |
76
+ | Retrieval | FAISS `IndexFlatIP` on L2-normalized vectors | Exact cosine-similarity search, top-k = 5 |
77
+ | Generation | `gpt-5.6-luna` via the OpenAI API | Hosted remotely. No generation model runs inside either Space |
78
+
79
+ ## Data
80
+
81
+ The index is built offline from MedQuAD:
82
+
83
+ - Remove exact duplicates and records with no answer
84
+ - Join each question and answer into one text field
85
+ - Split the text into 500-word chunks with a 50-word overlap
86
+ - Store each chunk with its source, focus area, and original question so
87
+ every answer can cite where it came from
88
+
89
+ ## Intended use
90
+
91
+ **Use it for** general, informational questions about conditions, symptoms,
92
+ and treatments that MedQuAD covers.
93
+
94
+ **Don't use it for** diagnosis, treatment or medication decisions,
95
+ emergencies, or questions about a specific patient.
96
+
97
+ ## API
98
+
99
+ The backend can also be called directly:
100
+
101
+ ```bash
102
+ curl -X POST https://whosouravsharma-medical-assistant-ai-backend.hf.space/ask \
103
+ -H "Authorization: Bearer $HF_TOKEN" \
104
+ -H "Content-Type: application/json" \
105
+ -d '{"question": "What are the symptoms of glaucoma?"}'
106
+ ```
107
+
108
+ The response contains `query`, `answer`, and `sources`. Each source has its
109
+ rank, similarity score, source name, focus area, original question, and the
110
+ chunk text.
111
+
112
+ ## Setup (for forks / redeploys)
113
+
114
+ Set these as Space secrets or variables:
115
+
116
+ | Name | Purpose |
117
+ |---|---|
118
+ | `BACKEND_URL` | Backend Space URL: `https://whosouravsharma-medical-assistant-ai-backend.hf.space` |
119
+ | `HF_TOKEN` | Sent as a bearer token to the backend. Authentication is token-based and there is no user login |
120
+
121
+ ## Limitations
122
+
123
+ - Answers are limited to what MedQuAD covers. For questions outside it, the
124
+ model is told to say the retrieved information is insufficient rather
125
+ than guess.
126
+ - The grounding prompt reduces hallucination risk but doesn't remove it,
127
+ and it hasn't been formally evaluated.
128
+ - Generation depends on a third-party hosted model. Its behaviour can only
129
+ be shaped through the prompt.
130
+ - No latency, cost, or accuracy benchmarks have been published yet.
131
+ - The embedding model is general-purpose and hasn't been tuned for medical
132
+ text.