An end-to-end Explainable AI (XAI) research project that introduces a novel "Two-Gate Head-Split" neural network architecture for tabular data. This repository contains the full lifecycle of the research, from initial conceptual experiments on MNIST to real-world validation on large-scale HMDA (Home Mortgage Disclosure Act) tabular data and a final LLM-powered explanation UI.

• Novel Two-Gate Architecture: Instead of a traditional black-box DNN, the model splits raw tabular input into two distinct gating mechanism paths (Gate A and Gate B).
  • Gate A learns to select features that maximize Class 1 (e.g., Loan Denied).
  • Gate B learns to select features that maximize Class 0 (e.g., Loan Approved).
• Head-Split Prediction: The gated outputs go through a shared backbone and are split into two heads. The final prediction is driven by the subtraction of the logits, making feature-level reasoning inherent to the model's design.
• Inherent Interpretability (Anchor & Neighbors): Because the network separates feature importance for positive and negative classes via gates, we can accurately measure specific feature impact for any prediction and use latent z-space to find highly relevant semantic neighbors (similar & counterfactual cases).
• LLM Explanation UI: We pipe the interpretable outputs (Gate values, Anchor/Neighbor instances) into leading LLMs (OpenAI, Gemini) to generate natural, human-readable explanations via a web UI.

├── ex/ # Proof of Concept (PoC) Experiments
│ └── experiments_exp* # Gradual progression from single gate -> 2-gate -> head-split on MNIST.
├── hmda_lar_md_2024/ # Real-World Tabular Data Application
│ ├── headplit/ # Implementation of the Two-Gate Head-Split model
│ ├── nogate/ # Standard DNN baseline
│ ├── onegate/ # Single Gate baseline
│ └── compare_models.py # Validation scripts to compare F1, precision, recall
├── mnist_headsplit/ # Visual Interpretability Validation
│ └── visualisations # Overlays demonstrating which pixels Gate A & Gate B focus on
├── hmda_sim_ui/ # LLM-powered Explanation Web UI
│ ├── app.js & index.html # Frontend dashboard
│ ├── run_openai_cards.py # Generates explanations via OpenAI
│ └── run_gemini_cards.py # Generates explanations via Google Gemini
├── assets/ # Architecture diagrams and system flowcharts
└── README.md

Our proposed architecture forces the model to inherently decide why it predicts one class over the other by maintaining two distinct feature-spaces from the input layer.

Two-Gate Head-Split Architecture

Two-Gate Head-Split Explanation Pipeline

For detailed flow generation rules, check twogate_headsplit_arch_prompt.txt and twogate_explanation_pipeline_prompt.txt in the root.

To make the AI transparent to end users, the tabular insights derived from the model's gate values and neighbor embeddings are transformed into UI-friendly explanatory "Cards" using an LLM.

LLM Explanation UI

• Python 3.9+
• Node.js (for UI testing)
• Access to HMDA md_2018.csv ~ md_2024.csv if training the tabular pipeline from scratch.

1. Navigate to the UI folder:

   cd hmda_sim_ui

2. Generate the LLM cards (requires API keys):

   python run_openai_cards.py
   # or
   python run_gemini_cards.py

3. Open index.html in your web browser or serve it locally to interact with the LLM explanations.

This project is open-source and available under the standard MIT License.