README.md

metadata

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

🎯 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

# 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

# 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. 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 for details.

🔗 References

• Graph-of-Thoughts - Besta et al., AAAI 2024
• Reasoning on Graphs - Luo et al., ICLR 2024
• Representation Engineering - Zou et al., 2023

---

Built with ❤️ for explainable medical AI research