🧠 Neuro-Symbolic Medical Expert System

Endemic West African Febrile Illness Differentiator

A GUI-based clinical decision-support tool that combines Google Gemini LLM intelligence with a MYCIN-inspired symbolic inference engine to differentiate four endemic West African febrile illnesses: Malaria, Typhoid, Dengue, and Lassa Fever.

🔬 Overview

This system implements a neuro-symbolic approach to medical diagnosis:

Layer	Role	Technology
Neural	Understands free-text patient complaints and extracts structured symptoms	Google Gemini 2.5 Flash
Unification	Maps neural output onto the symbolic knowledge base vocabulary	Python rule-based mapping
Symbolic	Performs evidence-weighted inference using certainty factor mathematics	MYCIN-based forward & backward chaining
Explanation	Produces a full audit trail of every rule fired and calculation made	JSON audit trail + formatted output

The system is not a black box — every diagnostic conclusion is fully traceable through its audit trail.

🏗 Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Patient Complaint                          │
│              "I have a pounding headache and pain               │
│               behind my eyes, and I feel very weak"             │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │    NEURAL LAYER        │
              │   (Gemini 2.5 Flash)   │
              │                        │
              │  Extracts symptoms as  │
              │  structured JSON with  │
              │  certainty factors     │
              └───────────┬────────────┘
                          │
                          ▼
              ┌────────────────────────┐
              │   UNIFICATION LAYER    │
              │                        │
              │  Maps neural output    │
              │  → KB vocabulary       │
              │  Logs unmapped to file │
              └───────────┬────────────┘
                          │
                          ▼
              ┌────────────────────────┐
              │   INFERENCE ENGINE     │
              │  (Evidence-Weighted    │
              │       DAG)             │
              │                        │
              │  Forward Chaining ──►  │
              │  Backward Chaining ──► │
              │  MYCIN CF Maths        │
              └───────────┬────────────┘
                          │
                          ▼
              ┌────────────────────────┐
              │   EXPLANATION          │
              │     FACILITY           │
              │                        │
              │  Audit trail (JSON)    │
              │  Diagnostic report     │
              │  CF bar charts         │
              └────────────────────────┘

⚙ How It Works

1. Symptom Extraction (Neural Layer)

The patient types a free-text complaint. Gemini parses it into a strict JSON dictionary:

Patient: "I've had a terrible headache and my eyes hurt behind them, and I feel really weak"

{
  "headache": 0.95,
  "retro_orbital_pain": 0.90,
  "general_weakness": 0.85
}

2. Vocabulary Unification

The extracted symptoms are matched against the 23 recognised symptom keys in knowledge_base.json. Any valid but unrecognised symptoms are logged to unmapped_symptoms.log for future KB expansion.

3. Forward Chaining

The engine iterates every rule. When all conditions of a rule are present in the evidence, the rule fires. Multiple rules supporting the same disease are combined using parallel (incremental evidence) combination.

4. Backward Chaining

If the highest-confidence diagnosis is below the threshold (default: 0.40), the engine identifies the top hypothesis, finds which symptoms are missing from its rules, and asks the user directly:

➤ Do you have 'Severe Bone Joint Pain'? (Enter CF 0.0–1.0, or 0 if absent):

It then re-runs forward chaining with the augmented evidence set.

5. Explanation & Audit Trail

Every rule that fired, the symptoms that triggered it, and the exact mathematical calculation are recorded and printed.

📁 Project Structure

ExpertSystemforMedDiag/
│
├── app.py                      # Flask Web Server — API & Frontend Handler
├── main.py                     # CLI Entry point — thin launcher
├── evaluate.py                 # Batch evaluator for comparative benchmarking
├── knowledge_base.json         # Decoupled disease rules & symptom vocabulary
├── requirements.txt            # Python dependencies
├── .env                        # Your Gemini API key (create from .env.example)
├── .env.example                # Template for the .env file
├── vignettes_dataset.csv       # Benchmark dataset (expected by evaluate.py)
├── evaluation_results.json     # Generated benchmark metrics output (after evaluation)
├── unmapped_symptoms.log       # Auto-generated log of unrecognised symptoms
├── README.md                   # This file
│
├── templates/                  # HTML Templates (Single Page App)
│   └── index.html              # The Web UI
│
├── static/                     # Frontend Assets
│   ├── app.js                  # Frontend Logic (API calls, DAG rendering)
│   └── style.css               # Custom Styles
│
└── engine/                     # Core package (clean architecture)
    ├── __init__.py             # Public API exports
    ├── __main__.py             # Allows: python -m engine
    ├── config.py               # Constants, paths, .env loading, Gemini prompt
    ├── knowledge_base.py       # KnowledgeBase class (loads & queries the KB)
    ├── neural_layer.py         # GeminiNeuralLayer (Gemini API integration)
    ├── unification.py          # UnificationLayer (neural → symbolic mapping)
    ├── inference.py            # InferenceEngine (forward/backward chaining)
    ├── explanation.py          # ExplanationFacility (audit trail & reporting)
    └── orchestrator.py         # run() — main consultation loop

Module Responsibilities

Module	Class / Function	Responsibility
`config.py`	—	Loads `.env`, defines all constants, paths, thresholds, and the Gemini system prompt
`knowledge_base.py`	`KnowledgeBase`	Loads `knowledge_base.json`, exposes disease rules and symptom vocabulary
`neural_layer.py`	`GeminiNeuralLayer`	Sends complaints to Gemini, parses the structured JSON response, handles retries
`unification.py`	`UnificationLayer`	Splits neural output into mapped (in KB) and unmapped symptoms; logs unmapped
`inference.py`	`InferenceEngine`	Forward & backward chaining with MYCIN CF series/parallel combination
`explanation.py`	`ExplanationFacility`	Formats the audit trail as JSON and a human-readable report
`orchestrator.py`	`run()`	Wires all components together in the interactive consultation loop

🚀 Setup & Installation

Prerequisites

Python 3.13+
A Google Gemini API key — get one free at Google AI Studio

Steps

# 1. Clone the repository
git clone https://github.com/Mopheshi/ExpertSystemforMedDiag.git
cd ExpertSystemforMedDiag

# 2. Create and activate a virtual environment
python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS / Linux:
# source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up your API key (ONE-TIME setup)
copy .env.example .env
# Then edit .env and replace 'your-api-key-here' with your actual key

💡 You only set the API key once. It's stored in .env and loaded automatically every time you run the program.

💻 Usage

Run the system

Option 1: Web Interface (Recommended)

python app.py
# Open http://127.0.0.1:5000 in your browser

Option 2: CLI Mode

python main.py
# or
python -m engine

Example Session

════════════════════════════════════════════════════════════════════════
  NEURO-SYMBOLIC MEDICAL EXPERT SYSTEM
  Endemic West African Febrile Illness Differentiator
  (Malaria · Typhoid · Dengue · Lassa Fever)
════════════════════════════════════════════════════════════════════════

  ✔ Knowledge Base loaded: KnowledgeBase(diseases=['malaria', ...], rules=8, symptoms=23)
  ✔ Gemini Neural Layer initialised (model: gemini-2.5-flash)

────────────────────────────────────────────────────────────────────────
  Enter patient complaint (or 'quit' to exit):
  ➤ I have a pounding headache and pain behind my eyes, with severe joint pain

  ⏳ Sending complaint to Gemini for symptom extraction…
  ✔ Gemini extracted 3 symptom(s): {'headache': 0.95, 'retro_orbital_pain': 0.90, ...}
  ✔ Mapped to KB: 3 symptom(s)

  ⏳ Running forward chaining…

════════════════════════════════════════════════════════════════════════
  DIAGNOSTIC REPORT – Neuro-Symbolic Expert System
════════════════════════════════════════════════════════════════════════

  ▸ FINAL DISEASE CERTAINTY FACTORS:

    Dengue               [████████████████████████░░░░░░] 0.8100
    Malaria              [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0.0000
    Typhoid              [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0.0000
    Lassa Fever          [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0.0000

  ✦ MOST LIKELY DIAGNOSIS: DENGUE  (CF = 0.8100)

Type quit, exit, or q to end the session.

📈 Comparative Benchmarking

The project now includes evaluate.py for side-by-side empirical comparison of three systems on the same vignette dataset:

Neuro-Symbolic (full pipeline)
Pure LLM (direct Gemini diagnosis)
Classical Rule-Based (keyword matching + symbolic inference)

Run Benchmark

# Uses default dataset: vignettes_dataset.csv
python evaluate.py

# Explicit dataset path
python evaluate.py --dataset vignettes_dataset.csv --delay 2.0

# Offline/low-cost mode: skip direct LLM baseline
python evaluate.py --dataset vignettes_dataset.csv --skip-llm

Required Dataset Columns

evaluate.py expects these CSV columns:

vignette_id
true_label
vignette_text

Benchmark Outputs

Per-system classification reports in terminal
Side-by-side precision/recall/F1 comparison table in terminal
LaTeX table block for paper inclusion (printed in terminal)
Reproducibility artefact saved to evaluation_results.json

📚 Knowledge Base

The knowledge base (knowledge_base.json) is a decoupled, editable JSON file containing:

4 diseases: Malaria, Typhoid, Dengue, Lassa Fever
8 evidence-based rules (2–3 per disease) with pathognomonic symptom sets
23 unique symptom keys in a controlled vocabulary

Recognised Symptom Vocabulary

Malaria	Typhoid	Dengue	Lassa Fever
`high_temperature`	`gradually_increasing_high_fever`	`sudden_high_fever_40C`	`slight_fever`
`chills_and_rigors`	`abdominal_pain`	`retro_orbital_pain`	`facial_and_neck_swelling`
`heavy_sweating`	`constipation`	`severe_bone_joint_pain`	`general_weakness`
`cyclical_fever_48h`	`persistent_fever`		`fever`
`headache`	`rose_spots_rash_on_trunk`		`deafness_or_hearing_loss`
`jaundice_yellow_eyes`	`extreme_tiredness`		`chest_pain`
			`mucosal_bleeding_eyes_gums`
			`difficulty_breathing`

Adding New Rules

Edit knowledge_base.json directly. Each rule follows this schema:

{
  "id": "R10",
  "hypothesis": "disease_name",
  "conditions": [
    {"symptom": "symptom_key_1"},
    {"symptom": "symptom_key_2"}
  ],
  "rule_cf": 0.85
}

📐 CF Mathematics (MYCIN)

The inference engine implements the classic MYCIN certainty factor formulas:

Series Combination (AND Logic)

When a rule requires multiple symptoms, the minimum symptom CF is used (weakest-link principle), then multiplied by the rule's base confidence:

$$CF_{rule} = \min(CF_{symptom_1},\ CF_{symptom_2},\ \ldots) \times Rule_{Base_CF}$$

Parallel Combination (Incremental Evidence)

When multiple rules support the same disease, their CFs are combined using the remaining uncertainty margin — ensuring the combined CF never exceeds 1.0:

$$CF_{combine} = CF_{old} + CF_{new} \times (1 - CF_{old})$$

Example Calculation

Rule R05 fires for Dengue:
  Symptoms: sudden_high_fever_40C=0.90, retro_orbital_pain=0.85, severe_bone_joint_pain=0.80
  Series:   min(0.90, 0.85, 0.80) × 0.90 = 0.7200
  Parallel: 0.0000 + 0.7200 × (1 − 0.0000) = 0.7200

📊 Audit Trail & Explainability

The system is not a black box. Every consultation produces:

Extracted symptoms with their certainty factors
Unmapped symptoms logged for KB expansion
Rule firing trace — which rules fired, which symptoms triggered them, and the exact maths
CF bar chart — visual comparison of all disease hypotheses
Full JSON audit trail — machine-readable record of the entire inference

[
  {
    "rule_id": "R05",
    "hypothesis": "dengue",
    "matched_symptoms": {
      "sudden_high_fever_40C": 0.90,
      "retro_orbital_pain": 0.85,
      "severe_bone_joint_pain": 0.80
    },
    "min_symptom_cf": 0.80,
    "rule_base_cf": 0.90,
    "series_cf": 0.7200,
    "previous_disease_cf": 0.0000,
    "new_disease_cf": 0.7200,
    "formula_series": "min(0.90, 0.85, 0.80) × 0.90 = 0.7200",
    "formula_parallel": "0.0000 + 0.7200 × (1 − 0.0000) = 0.7200"
  }
]

⚙️ Configuration

All tunable parameters live in engine/config.py:

Parameter	Default	Description
`BACKWARD_CHAIN_THRESHOLD`	`0.4`	CF below which backward chaining is triggered
`GEMINI_MODEL`	`gemini-2.5-flash`	Gemini model to use for symptom extraction
`GEMINI_MAX_RETRIES`	`3`	Max retry attempts on rate-limit (429) errors
`GEMINI_INITIAL_BACKOFF_SECS`	`30.0`	Initial wait time before first retry (doubles each attempt)

Environment Variables

Variable	Required	Description
`GEMINI_API_KEY`	✅	Your Google Gemini API key. Set in `.env` file.

🔧 Troubleshooting

Error	Cause	Solution
`GEMINI_API_KEY environment variable is not set`	Missing `.env` file or key	Copy `.env.example` to `.env` and add your key
`429 RESOURCE_EXHAUSTED`	Free-tier Gemini quota used up	Wait for daily reset or upgrade at ai.dev/rate-limit
`Knowledge base not found`	`knowledge_base.json` missing or moved	Ensure it's in the project root directory
`Dataset not found: vignettes_dataset.csv`	Incorrect file path or wrong working directory	Run from project root, or pass an absolute path to `--dataset`
`No rules were triggered`	Extracted symptoms don't match any full rule set	The system will attempt backward chaining to gather more evidence

⚕️ Disclaimer

This is a decision-support tool for educational and research purposes only. It is not a substitute for professional medical advice, diagnosis, or treatment. A qualified clinician must confirm any diagnosis. Always seek the advice of your physician or other qualified health provider with any questions you may have regarding a medical condition.

Built with 🧠 Neuro-Symbolic AI — where neural understanding meets symbolic reasoning.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.idea		.idea
engine		engine
static		static
templates		templates
.env.example		.env.example
.gitignore		.gitignore
LICENCE		LICENCE
README.md		README.md
app.py		app.py
evaluate.py		evaluate.py
evaluation_results.json		evaluation_results.json
knowledge_base.json		knowledge_base.json
main.py		main.py
requirements.txt		requirements.txt
unmapped_symptoms.log		unmapped_symptoms.log
vignettes_dataset.csv		vignettes_dataset.csv

Folders and files

Latest commit

History

Repository files navigation

🧠 Neuro-Symbolic Medical Expert System

Endemic West African Febrile Illness Differentiator

📋 Table of Contents

🔬 Overview

🏗 Architecture

⚙ How It Works

1. Symptom Extraction (Neural Layer)

2. Vocabulary Unification

3. Forward Chaining

4. Backward Chaining

5. Explanation & Audit Trail

📁 Project Structure

Module Responsibilities

🚀 Setup & Installation

Prerequisites

Steps

💻 Usage

Run the system

Example Session

📈 Comparative Benchmarking

Run Benchmark

Required Dataset Columns

Benchmark Outputs

📚 Knowledge Base

Recognised Symptom Vocabulary

Adding New Rules

📐 CF Mathematics (MYCIN)

Series Combination (AND Logic)

Parallel Combination (Incremental Evidence)

Example Calculation

📊 Audit Trail & Explainability

⚙️ Configuration

Environment Variables

🔧 Troubleshooting

⚕️ Disclaimer

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages