---
title: HITL-KG Medical Reasoning
emoji: ⚕️
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Interactive medical reasoning with knowledge graph steering
---

# Human-in-the-Loop Knowledge Graph Steering System

> **Interactive visualization and real-time steering of LLM reasoning through medical knowledge graphs**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![Dash](https://img.shields.io/badge/Dash-2.14+-green.svg)](https://dash.plotly.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🎯 Overview

This system implements a novel approach to explainable AI in the medical domain by externalizing LLM reasoning as an interactive, editable graph structure. Users can:

- **Visualize** the model's diagnostic reasoning process in real-time
- **Intervene** by pruning incorrect branches or resurrecting alternative diagnoses
- **Inject** medical facts from a comprehensive knowledge base
- **Steer** reasoning toward correct conclusions through visual manipulation

## ✨ Features

### 🔬 Medical Knowledge Graph
- **50+ medical entities** including symptoms, diseases, and treatments
- **SNOMED-CT inspired** ontology structure
- **Weighted relationships** for probabilistic reasoning

### 🧠 LLM Integration
- **OpenAI GPT-4** for advanced reasoning (when API key provided)
- **Local KG-based** reasoning as fallback
- **Structured output** with confidence scores

### 🎮 Interactive Steering
| Action | Description |
|--------|-------------|
| **Prune** | Remove incorrect reasoning branches |
| **Resurrect** | Activate alternative diagnostic paths |
| **Inject** | Add medical facts to guide reasoning |

## 🚀 Quick Start

### Local Development

```bash
# Clone repository
git clone https://github.com/your-org/hitl-kg-medical.git
cd hitl-kg-medical

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set OpenAI API key (optional)
export OPENAI_API_KEY=your-key-here

# Run application
python app.py
```

Open http://localhost:7860 in your browser.

### Docker Deployment

```bash
# Build image
docker build -t hitl-kg-medical .

# Run container
docker run -p 7860:7860 -e OPENAI_API_KEY=your-key hitl-kg-medical
```

### Hugging Face Spaces

This application is designed for deployment on [Hugging Face Spaces](https://huggingface.co/spaces). Simply push to a Space with the Docker SDK selected.

To configure OpenAI:
1. Go to Space Settings → Repository Secrets
2. Add `OPENAI_API_KEY` with your API key

## 📖 Usage Guide

### 1. Enter Your Symptoms
Type your symptoms in the chat interface:
```
"I have fever, cough, and fatigue for 3 days"
```

### 2. Review the Reasoning Graph
The system generates a visual reasoning chain:
- **Query** (💎) → Your original question
- **Facts** (🟢) → Knowledge from the medical graph
- **Reasoning** (🔵) → Intermediate analysis steps
- **Hypotheses** (🟡) → Possible diagnoses
- **Conclusion** (⭐) → Final recommendation

### 3. Steer the Reasoning
- **Click** nodes to view details
- **Prune** incorrect branches
- **Resurrect** alternative diagnoses (ghost nodes)
- **Inject** additional medical facts

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Dash + Cytoscape)              │
│  Chat Interface │ Graph Canvas │ Steering Controls          │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                  Middleware (Graph Synchronizer)            │
│  Context Management │ Tree Cache │ Edit History             │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│                   Backend (LLM + Knowledge Graph)           │
│  OpenAI/Local Engine │ Medical KG │ Entity Linking          │
└─────────────────────────────────────────────────────────────┘
```

## 📁 Project Structure

```
hitl-kg-project/
├── app.py                     # Main application
├── Dockerfile                 # Container configuration
├── requirements.txt           # Dependencies
├── README.md                  # This file
├── src/
│   ├── core/
│   │   ├── knowledge_graph.py # Medical KG implementation
│   │   └── llm_engine.py      # LLM integration
│   └── styles/
│       └── cytoscape_styles.py # Visual styling
└── data/
    └── medical_kg.json        # Knowledge graph data
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `OPENAI_API_KEY` | OpenAI API key for GPT-4 reasoning | No |
| `HF_TOKEN` | Hugging Face token for private models | No |
| `PORT` | Server port (default: 7860) | No |

### LLM Providers

1. **OpenAI** (Recommended)
   - Requires `OPENAI_API_KEY`
   - Uses GPT-4o-mini for structured medical reasoning
   - Best quality reasoning output

2. **Local** (Fallback)
   - No API key required
   - Uses knowledge graph-based reasoning
   - Works offline

## 🔬 Medical Knowledge Base

The system includes a comprehensive medical knowledge graph with:

- **Symptoms**: Fever, Cough, Fatigue, Headache, Shortness of Breath, etc.
- **Diseases**: Influenza, COVID-19, Common Cold, Pneumonia, Bronchitis, etc.
- **Treatments**: Rest, Fluids, Antivirals, Antibiotics, etc.

All entities include:
- SNOMED-CT inspired coding
- Detailed descriptions
- Synonyms for entity linking
- Weighted cause-effect relationships

## ⚠️ Disclaimer

**This tool is for educational and research purposes only.**

- Do NOT use for actual medical diagnosis
- Always consult qualified healthcare professionals
- The knowledge graph is simplified and not comprehensive
- AI reasoning can be incorrect or biased

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🔗 References

- [Graph-of-Thoughts](https://arxiv.org/abs/2308.09687) - Besta et al., AAAI 2024
- [Reasoning on Graphs](https://arxiv.org/abs/2310.01061) - Luo et al., ICLR 2024
- [Representation Engineering](https://arxiv.org/abs/2310.01405) - Zou et al., 2023

---

**Built with ❤️ for explainable medical AI research**