KEditVis: Interactive Visual Analytics for Human-in-the-Loop Knowledge Editing in Large Language Models

Grounded in human-in-the-loop visual analytics for autoregressive Transformer editing.

---

Table of Contents

1. Overview
2. System Architecture
3. Key Empirical Findings
4. Core Differences: 2603.29689v1.pdf vs. Our Implementation
5. Repository Structure
6. Quickstart & Installation
7. Running the Test Suites
8. Cloud GPU Backend Deployment
9. Benchmarking & Reproduction
10. Academic Reconciliation
11. References

---

Overview

Large Language Models (LLMs) store vast amounts of factual knowledge within their feedforward weight matrices (W_out). When facts become outdated or require correction, retraining the entire network is computationally prohibitive. Locate-then-edit techniques—principally ROME (Rank-One Model Editing) and MEMIT (Mass-Editing Memory in a Transformer)—treat feedforward layers as linear associative memories, modifying weights to store new associations:

W_{\text{new}} = W_0 + \Delta W

The Problem with Static Presets

Production editing pipelines typically rely on rigid, model-wide layer presets (e.g., layers [13..17] for GPT-2-XL, layers [3..7] for GPT-J-6B). However, factual representations do not localize identically across different entities and semantic categories:

• Mislocated Edits: Editing outside the factual storage locus fails to generalize or destroys model coherence.
• Parameter Explosion: Unconstrained random layer selection induces up to 11.3x higher relative Frobenius parameter drift (||ΔW||_F / ||W_0||_F), destabilizing nearby knowledge.
• Paraphrase Fragility: Standard single-context MEMIT often succeeds on the literal target prompt but fails under varied phrasing.

The KEditVis Solution

KEditVis is an end-to-end interactive visual analytics system that integrates human domain judgment directly into the editing loop. By extracting layer-wise residual variance Var_dim(h_l[t]), directional cosine similarity dips, and logit-lens vocabulary projections in real time, KEditVis guides practitioners to stable layer bands, monitors parameter drift, and provides instantaneous, zero-drift transactional rollback.

---

System Architecture

                      +------------------------------------------+
                      |         KEditVis React Dashboard         |
                      |   (Vite + TailwindCSS + D3.js Visuals)   |
                      +---------------------+--------------------+
                                            |
                                            | REST API (HTTP / JSON)
                                            v
+---------------------------------------------------------------------------------------+
|                               FastAPI Backend (Modal A100)                             |
|                                                                                       |
|  +------------------------+   +------------------------+   +-----------------------+  |
|  |   Telemetry Extraction |   |   Editing Engine       |   |  Transactional State  |  |
|  | - Residual Variance    |   | - ROME                 |   | - Weight Snapshots    |  |
|  | - Cosine Similarity    |   | - Standard MEMIT       |   | - Zero-Drift Rollback |  |
|  | - Logit-Lens Projection|   | - Context-Robust MEMIT |   | - Frobenius Tracking  |  |
|  +------------------------+   +------------------------+   +-----------------------+  |
|                                           |                                           |
|                                           v                                           |
|                     HuggingFace Transformer Architecture                              |
|                     - GPT-2-XL (1.5B, 48 Transformer Layers)                          |
|                     - GPT-J-6B (6.0B, 28 Transformer Layers)                          |
+---------------------------------------------------------------------------------------+

Coordinated Visual Interfaces

1. Layer Telemetry Strip: Displays layer-by-layer residual variance and cosine similarity dips across subject tokens, pinpointing the critical information-processing layers.
2. Multi-Context Vocabulary Projections: Traces top-1 greedy token predictions across all layers via unembedding matrix projection (h_l · W_U).
3. Multi-Metric Comparative Workspace: Evaluates candidate layer selections and optimization profiles side-by-side across:
   • Efficacy Score (ES): Preference probability P(target) > P(original).
   • Paraphrase Score (PS): Generalization across unseen rephrasings.
   • Neighborhood Score (NS): Locality preservation on unedited sibling subjects.
4. Frobenius Parameter Drift & KL Scatter: Plots tensor weight deviation (||ΔW||_F) against hidden state representation divergence (D_KL), detecting localized over-fitting before committing changes.

---

Key Empirical Findings

Extensive evaluations across the standardized CounterFact benchmark on NVIDIA A100-SXM4-40GB hardware yielded concrete insights:

Insights

• Telemetry Layer Selection Acts as a Critical Safety Filter: While heuristic telemetry selection achieves parity with the static preset (S = 0.621 vs 0.631), its primary function is preventing catastrophic failure bands. Arbitrary layer selection causes an 11.3x explosion in parameter drift (Rel-Frob = 0.1071) with severe degradation in paraphrase generalization (PS = 0.40).
• Context-Robust MEMIT Rescues Fragile Edits: Expanding the latent update budget (40 steps, clamp 1.5) and applying multi-context fitting raises paraphrase generalization from 0.80 to 0.90, successfully resolving previously impossible hard edits (e.g., Wellington → Sheffield).
• Transactional Rollback Guarantees Safe Exploration: In-memory transactional weight snapshots guarantee 0.000 residual weight drift upon rollback, verified across all tests and live runs.

---

Core Differences: 2603.29689v1.pdf (Chen et al., TVCG 2026) vs. Our Implementation

The theoretical foundation of this project originates from the base paper:
Z. Chen et al., "KEditVis: A Visual Analytics System for Knowledge Editing of Large Language Models," IEEE Transactions on Visualization and Computer Graphics (TVCG), vol. 32, no. 6, pp. 4818–4828, June 2026 (arXiv:2603.29689v1).

While Chen et al. introduced the visual analytics workflow, our capstone project extends their theoretical design into an operational, mathematically validated, and open-source full-stack platform. Below are the core technical, algorithmic, and empirical differences:

Key Architectural Extensions

1. Residual Variance Operationalization: The base paper measured layer activity exclusively through cosine similarity between MLP inputs and outputs. Our implementation operationalized feature-wise hidden channel variance Var_dim(h_l[t]) and delta variance Var_dim(h_l - h_{l-1}), providing mathematically sound, scale/shift-invariant signals with interactive toggle controls in the UI.
2. Context-Robust Optimization: To address single-context MEMIT brittleness, we engineered a local CORE-inspired multi-context optimization engine in editing_optimizations.py that fits across multiple diverse prefixes and applies consistency regularization.
3. Rigorous Parameter Drift Quantification: While the paper relied on stochastic t-SNE projections that mask weight matrix destruction, our system computes exact tensor Frobenius norms (||ΔW||_F), proving that unconstrained layer selection causes an 11.3x explosion in parameter corruption.
4. Empirical Grounding: Rather than claiming speculative superiority, our controlled 10-fact CounterFact benchmarks scientifically demonstrate that telemetry layer selection functions primarily as an essential guardrail against destructive out-of-band layers.

---

Repository Structure

.
├── EVALUATION.md                       # Comprehensive empirical evaluation & claim reconciliation
├── README.md                           # Repository documentation (this file)
└── prototype/
    ├── modal_app.py                    # Production FastAPI backend deployed on Modal A100 GPU
    ├── editing_optimizations.py        # Context-robust MEMIT, loss functions & Frobenius drift
    ├── layer_selection.py              # Telemetry-based layer scoring and selection heuristics
    ├── local_probe.py                  # Standalone CLI probe for local GPU/CPU inspection
    ├── run_experiments.py              # Automated CounterFact benchmark execution pipeline
    ├── test_backend.py                 # Core backend unittests (FastAPI routes, rollback, invariance)
    ├── test_optimizations.py            # Optimization unittests (multi-context fitting, projections)
    ├── test_live.py                    # Live GPU integration verification suite
    ├── error_analysis.py               # Empirical diagnostic tool for hard/failing facts
    ├── export_doc.py                   # Automated docx generator matching university styling
    ├── verify_manifest.py              # Cryptographic SHA-256 verification manifest generator
    ├── data/
    │   └── benchmark_manifest.json     # Standardized 10-fact CounterFact evaluation dataset
    ├── audit/
    │   └── evaluation/
    │       ├── verification.json       # Cryptographic SHA-256 manifest of core artifacts
    │       ├── summary.json            # Aggregated benchmark metrics with bootstrap 95% CIs
    │       └── raw_results.json        # Raw per-fact execution logs
    └── frontend/                       # Interactive React 19 visual analytics dashboard
        ├── src/                        # TypeScript dashboard components (D3 charts, controls)
        ├── package.json                # Frontend dependencies
        └── tests/                      # Automated browser regression suites (Puppeteer)

---

Quickstart & Installation

1. Local Environment Setup

Clone the repository and prepare a Python virtual environment:

git clone https://github.com/umran666/KEditVis-LLM-Editing.git
cd KEditVis-LLM-Editing/prototype

python -m venv .venv
# On Windows:
.\.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt

2. Standalone Local Probe (Zero Cloud Dependencies)

You can run the layer-inspection probe locally on CPU or any consumer GPU (e.g., RTX 3050):

python local_probe.py --model gpt2-medium --prompt "{} is located in the city of" --subject "Eiffel Tower"

This will output an ASCII chart of layer-by-layer cosine similarities and logit-lens top token predictions.

3. Launching the Interactive Frontend

Navigate to the frontend directory, install packages, and launch the development server:

cd prototype/frontend
npm ci
npm run dev -- --host 127.0.0.1 --port 5187

Open http://127.0.0.1:5187 in your browser.

---

Running the Test Suites

Backend Unit Tests (CPU)

Run the complete regression suite covering route validation, transactional rollback, numerical invariance, and context optimizations:

cd prototype
python -m unittest test_backend.py test_optimizations.py -v

Expected output: Ran 22 tests in ~22s ... OK

Frontend Browser Regressions (Puppeteer)

Run the full end-to-end browser regression suite:

cd prototype/frontend
node tests/audit.mjs

Expected output: All 15 browser test groups passed with 0 errors.

---

Cloud GPU Backend Deployment

The backend runs on Modal utilizing an NVIDIA A100-SXM4-40GB GPU instance.

# 1. Install modal and authenticate
pip install modal
modal setup

# 2. Deploy the FastAPI app to production
cd prototype
modal deploy modal_app.py

The deployed endpoint will be output in the console and should be configured in prototype/frontend/.env.local:

VITE_API_BASE_URL=https://<your-username>--keditvis-memit-web-app.modal.run

---

Benchmarking & Reproduction

To reproduce the full 10-fact CounterFact benchmark matrix across static, telemetry, arbitrary, and context-robust conditions:

cd prototype
python run_experiments.py --live

To update cryptographic verification manifests:

# Cryptographically verify and hash all core artifacts
python verify_manifest.py

---

Academic Reconciliation

The initial project proposal set ambitious benchmarks for automated layer selection. Through rigorous empirical testing on real A100 hardware, our findings provide a more nuanced, scientifically honest contribution:

• Rather than outperforming optimized static baselines across every single metric, telemetry-guided selection operates as a robust guardrail, preventing the catastrophic drift and failure modes caused by arbitrary layer choice.
• For complete claim-by-claim analysis, bootstrap confidence intervals, and failure case diagnostics, see EVALUATION.md.

---

References

1. Meng, K., et al. (2022). Locating and Editing Factual Associations in GPT. Advances in Neural Information Processing Systems (NeurIPS 2022). arXiv:2202.05262.
2. Meng, K., et al. (2023). Mass-Editing Memory in a Transformer. International Conference on Learning Representations (ICLR 2023). arXiv:2210.07229.
3. Chen, Z., Zhan, H., Huang, Y., Wu, X., Deng, D., Weng, D., & Wu, Y. (2026). KEditVis: A Visual Analytics System for Knowledge Editing of Large Language Models. IEEE Transactions on Visualization and Computer Graphics (TVCG), vol. 32, no. 6, pp. 4818–4828. arXiv:2603.29689v1.
4. Geva, M., et al. (2021). Transformer Feed-Forward Layers Are Key-Value Memories. Empirical Methods in Natural Language Processing (EMNLP 2021). arXiv:2012.14913.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.