# allu555/medical-chatbot architecture

> Architecture diagram of the GitHub repository allu555/medical-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allu555/medical-chatbot
- Repository: https://github.com/allu555/medical-chatbot

## Overview

Sorin-AI is a medical conversational assistant whose primary workflow takes a patient query through emergency triage, then—if routine—retrieves medical references and generates a cited response in a Gradio interface. Its supporting branches build the retrieval index, train/load a local model, and evaluate response quality and safety. The README documents the overall pipeline; source excerpts and the SOURCE INDEX substantiate only some implementation calls, so other documented relationships are cited to the README or omitted.

Main entry points: [`app.py`](https://github.com/allu555/medical-chatbot/blob/main/app.py) (Gradio consultation UI), [`src/inference/generate.py`](https://github.com/allu555/medical-chatbot/blob/main/src/inference/generate.py) (Clinical response generation), [`src/rag/retriever.py`](https://github.com/allu555/medical-chatbot/blob/main/src/rag/retriever.py) (Medical retrieval), [`src/inference/safety.py`](https://github.com/allu555/medical-chatbot/blob/main/src/inference/safety.py) (Emergency pattern gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Patient conversation"]
  node_web_app["Gradio consultation UI<br/>[app.py]"]
  node_triage["Emergency pattern gate<br/>[safety.py]"]
  node_semantic_triage["Semantic triage<br/>[gemini_client.py]"]
  node_emergency["Emergency guidance<br/>[app.py]"]
  node_generator["Clinical response generation<br/>[generate.py]"]
end

subgraph group_knowledge["Medical knowledge RAG"]
  node_knowledge_docs["Curated medical documents"]
  node_knowledge_base["Document loading and chunking<br/>[knowledge_base.py]"]
  node_index_builder["Embedding index builder<br/>[build_index.py]"]
  node_faiss_store[("FAISS index and metadata")]
  node_retriever["Medical retrieval<br/>[retriever.py]"]
end

subgraph group_models["Model inference and training"]
  node_local_model["Local model loader<br/>[model_loader.py]"]
  node_dataset_prep["Dataset preparation<br/>[prepare_dataset.py]"]
  node_qlora_training["QLoRA training<br/>[train_qlora.py]"]
end

subgraph group_evaluation["Safety and evaluation"]
  node_response_eval["Model response evaluation<br/>[evaluate_model.py]"]
  node_rag_eval["Retrieval evaluation<br/>[evaluate_rag.py]"]
  node_heldout_eval["Held-out triage validation"]
end

node_patient(("Patient"))
node_gemini_service["Google Gemini API"]

node_patient -->|"submits query"| node_web_app
node_web_app -->|"checks symptoms"| node_triage
node_web_app -->|"classifies urgency"| node_semantic_triage
node_semantic_triage -.->|"requests triage"| node_gemini_service
node_web_app -->|"shows escalation"| node_emergency
node_web_app -->|"retrieves context"| node_retriever
node_web_app -->|"requests response"| node_generator
node_generator -->|"loads model"| node_local_model
node_generator -->|"validates output"| node_triage
node_generator -.->|"gets references"| node_retriever
node_generator -.->|"returns answer"| node_web_app
node_knowledge_docs -.->|"loads documents"| node_knowledge_base
node_index_builder -->|"loads and chunks"| node_knowledge_base
node_index_builder -.->|"writes index"| node_faiss_store
node_retriever -.->|"searches index"| node_faiss_store
node_dataset_prep -.->|"prepares training data"| node_qlora_training
node_response_eval -->|"evaluates responses"| node_generator
node_response_eval -->|"uses retrieval"| node_retriever
node_rag_eval -->|"measures retrieval"| node_retriever
node_heldout_eval -->|"tests detection"| node_triage

click node_web_app "https://github.com/allu555/medical-chatbot/blob/main/app.py"
click node_triage "https://github.com/allu555/medical-chatbot/blob/main/src/inference/safety.py"
click node_semantic_triage "https://github.com/allu555/medical-chatbot/blob/main/src/inference/gemini_client.py"
click node_emergency "https://github.com/allu555/medical-chatbot/blob/main/app.py"
click node_generator "https://github.com/allu555/medical-chatbot/blob/main/src/inference/generate.py"
click node_knowledge_docs "https://github.com/allu555/medical-chatbot/tree/main/knowledge_base/documents"
click node_knowledge_base "https://github.com/allu555/medical-chatbot/blob/main/src/rag/knowledge_base.py"
click node_index_builder "https://github.com/allu555/medical-chatbot/blob/main/src/rag/build_index.py"
click node_faiss_store "https://github.com/allu555/medical-chatbot/tree/main/artifacts/faiss"
click node_retriever "https://github.com/allu555/medical-chatbot/blob/main/src/rag/retriever.py"
click node_local_model "https://github.com/allu555/medical-chatbot/blob/main/src/inference/model_loader.py"
click node_dataset_prep "https://github.com/allu555/medical-chatbot/blob/main/src/data/prepare_dataset.py"
click node_qlora_training "https://github.com/allu555/medical-chatbot/blob/main/src/training/train_qlora.py"
click node_response_eval "https://github.com/allu555/medical-chatbot/blob/main/src/evaluation/evaluate_model.py"
click node_rag_eval "https://github.com/allu555/medical-chatbot/blob/main/src/evaluation/evaluate_rag.py"
click node_heldout_eval "https://github.com/allu555/medical-chatbot/blob/main/evaluate_heldout.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_triage,node_semantic_triage,node_emergency,node_generator toneBlue
class node_knowledge_docs,node_knowledge_base,node_index_builder,node_faiss_store,node_retriever toneAmber
class node_local_model,node_dataset_prep,node_qlora_training,node_gemini_service toneMint
class node_response_eval,node_rag_eval,node_heldout_eval toneRose
class node_patient toneIndigo
```

## Components

### Patient conversation

- [Gradio consultation UI](https://github.com/allu555/medical-chatbot/blob/main/app.py): `app.py`
- [Emergency pattern gate](https://github.com/allu555/medical-chatbot/blob/main/src/inference/safety.py): `src/inference/safety.py`
- [Semantic triage](https://github.com/allu555/medical-chatbot/blob/main/src/inference/gemini_client.py): `src/inference/gemini_client.py`
- [Emergency guidance](https://github.com/allu555/medical-chatbot/blob/main/app.py): `app.py`
- [Clinical response generation](https://github.com/allu555/medical-chatbot/blob/main/src/inference/generate.py): `src/inference/generate.py`

### Medical knowledge RAG

- [Curated medical documents](https://github.com/allu555/medical-chatbot/tree/main/knowledge_base/documents): `knowledge_base/documents`
- [Document loading and chunking](https://github.com/allu555/medical-chatbot/blob/main/src/rag/knowledge_base.py): `src/rag/knowledge_base.py`
- [Embedding index builder](https://github.com/allu555/medical-chatbot/blob/main/src/rag/build_index.py): `src/rag/build_index.py`
- [FAISS index and metadata](https://github.com/allu555/medical-chatbot/tree/main/artifacts/faiss): `artifacts/faiss`
- [Medical retrieval](https://github.com/allu555/medical-chatbot/blob/main/src/rag/retriever.py): `src/rag/retriever.py`

### Model inference and training

- [Local model loader](https://github.com/allu555/medical-chatbot/blob/main/src/inference/model_loader.py): `src/inference/model_loader.py`
- [Dataset preparation](https://github.com/allu555/medical-chatbot/blob/main/src/data/prepare_dataset.py): `src/data/prepare_dataset.py`
- [QLoRA training](https://github.com/allu555/medical-chatbot/blob/main/src/training/train_qlora.py): `src/training/train_qlora.py`

### Safety and evaluation

- [Model response evaluation](https://github.com/allu555/medical-chatbot/blob/main/src/evaluation/evaluate_model.py): `src/evaluation/evaluate_model.py`
- [Retrieval evaluation](https://github.com/allu555/medical-chatbot/blob/main/src/evaluation/evaluate_rag.py): `src/evaluation/evaluate_rag.py`
- [Held-out triage validation](https://github.com/allu555/medical-chatbot/blob/main/evaluate_heldout.py): `evaluate_heldout.py`

### Other components

- **Patient**
- **Google Gemini API**

## Connections

- Patient → Gradio consultation UI: submits query (evidence: `README.md`)
- Gradio consultation UI → Emergency pattern gate: checks symptoms (evidence: `README.md`)
- Gradio consultation UI → Semantic triage: classifies urgency (evidence: `app.py`)
- Semantic triage → Google Gemini API: requests triage
- Gradio consultation UI → Emergency guidance: shows escalation (evidence: `app.py`)
- Gradio consultation UI → Medical retrieval: retrieves context (evidence: `README.md`)
- Gradio consultation UI → Clinical response generation: requests response (evidence: `README.md`)
- Clinical response generation → Local model loader: loads model (evidence: `src/inference/generate.py`)
- Clinical response generation → Emergency pattern gate: validates output (evidence: `src/inference/generate.py`)
- Clinical response generation → Medical retrieval: gets references
- Clinical response generation → Gradio consultation UI: returns answer (evidence: `app.py`)
- Curated medical documents → Document loading and chunking: loads documents
- Embedding index builder → Document loading and chunking: loads and chunks (evidence: `src/rag/build_index.py`)
- Embedding index builder → FAISS index and metadata: writes index
- Medical retrieval → FAISS index and metadata: searches index
- Dataset preparation → QLoRA training: prepares training data
- Model response evaluation → Clinical response generation: evaluates responses (evidence: `src/evaluation/evaluate_model.py`)
- Model response evaluation → Medical retrieval: uses retrieval (evidence: `src/evaluation/evaluate_model.py`)
- Retrieval evaluation → Medical retrieval: measures retrieval (evidence: `src/evaluation/evaluate_rag.py`)
- Held-out triage validation → Emergency pattern gate: tests detection (evidence: `evaluate_heldout.py`)
