Rename package and release materials to NodeLens.

Author: houman1359

.github/workflows/lint.yml

@@ -26,13 +26,13 @@ jobs:
         pip install "black==25.9.0" isort flake8 mypy ruff
 
     - name: Run black (code formatting)
-      run: black --check --diff src/alignment/ tests/ scripts/
+      run: black --check --diff src/nodelens/ tests/ scripts/
 
     - name: Run isort (import sorting)
-      run: isort --check-only --diff --profile black src/alignment/ tests/ scripts/
+      run: isort --check-only --diff --profile black src/nodelens/ tests/ scripts/
 
     - name: Run flake8 (linting)
-      run: flake8 src/alignment/ tests/ scripts/ --max-line-length=100 --ignore=E203,W503 || echo "Flake8 has warnings"
+      run: flake8 src/nodelens/ tests/ scripts/ --max-line-length=100 --ignore=E203,W503 || echo "Flake8 has warnings"
 
     - name: Run mypy (type checking)
-      run: mypy src/alignment/ --ignore-missing-imports --no-strict-optional || echo "Type checking has warnings"
+      run: mypy src/nodelens/ --ignore-missing-imports --no-strict-optional || echo "Type checking has warnings"

.github/workflows/release.yml

@@ -36,15 +36,15 @@ jobs:
       with:
         files: dist/*
         body: |
-          Public research-code release for LossLens.
+          Public research-code release for NodeLens.
 
-          The Python package is currently imported as `alignment`.
+          The Python package is imported as `nodelens`.
 
           ## Install From Source
 
           ```bash
-          git clone https://github.com/KempnerInstitute/alignment.git
-          cd alignment
+          git clone https://github.com/KempnerInstitute/nodelens.git
+          cd nodelens
           pip install -e .
           ```
 

.github/workflows/test.yml

@@ -45,7 +45,7 @@ jobs:
 
     - name: Run tests
       run: |
-        pytest tests/ -v --cov=src/alignment --cov-report=xml --cov-report=html --cov-report=term-missing --tb=short -ra
+        pytest tests/ -v --cov=src/nodelens --cov-report=xml --cov-report=html --cov-report=term-missing --tb=short -ra
 
     - name: Check coverage threshold
       run: |

CITATION.cff

@@ -1,9 +1,9 @@
 cff-version: 1.2.0
 message: "If you use this code or the Supernodes and SCAR artifacts, please cite the paper and archived release."
-title: "LossLens"
+title: "NodeLens"
 version: "0.2.0"
-repository-code: "https://github.com/KempnerInstitute/alignment"
-url: "https://github.com/KempnerInstitute/alignment"
+repository-code: "https://github.com/KempnerInstitute/nodelens"
+url: "https://github.com/KempnerInstitute/nodelens"
 license: "MIT"
 authors:
   - family-names: "Cherilyn"
@@ -23,7 +23,7 @@ preferred-citation:
       given-names: "Houman"
       affiliation: "Kempner Institute at Harvard University"
   year: 2026
-  url: "https://github.com/KempnerInstitute/alignment"
+  url: "https://github.com/KempnerInstitute/nodelens"
   identifiers:
     - type: url
       value: "https://huggingface.co/datasets/hsafaai/supernodes-scar-artifacts"

README.md

@@ -1,18 +1,18 @@
-# LossLens
+# NodeLens
 
-Loss-sensitive neural network analysis and structured pruning tools.
+Node and channel metrics for neural network interpretability, importance, and interventions.
 
-[![Tests](https://github.com/KempnerInstitute/alignment/actions/workflows/test.yml/badge.svg)](https://github.com/KempnerInstitute/alignment/actions/workflows/test.yml)
-[![Lint](https://github.com/KempnerInstitute/alignment/actions/workflows/lint.yml/badge.svg)](https://github.com/KempnerInstitute/alignment/actions/workflows/lint.yml)
-[![Documentation](https://github.com/KempnerInstitute/alignment/actions/workflows/docs.yml/badge.svg)](https://github.com/KempnerInstitute/alignment/actions/workflows/docs.yml)
-[![Release](https://github.com/KempnerInstitute/alignment/actions/workflows/release.yml/badge.svg)](https://github.com/KempnerInstitute/alignment/actions/workflows/release.yml)
+[![Tests](https://github.com/KempnerInstitute/nodelens/actions/workflows/test.yml/badge.svg)](https://github.com/KempnerInstitute/nodelens/actions/workflows/test.yml)
+[![Lint](https://github.com/KempnerInstitute/nodelens/actions/workflows/lint.yml/badge.svg)](https://github.com/KempnerInstitute/nodelens/actions/workflows/lint.yml)
+[![Documentation](https://github.com/KempnerInstitute/nodelens/actions/workflows/docs.yml/badge.svg)](https://github.com/KempnerInstitute/nodelens/actions/workflows/docs.yml)
+[![Release](https://github.com/KempnerInstitute/nodelens/actions/workflows/release.yml/badge.svg)](https://github.com/KempnerInstitute/nodelens/actions/workflows/release.yml)
 [![Python](https://img.shields.io/badge/python-%3E%3D3.8-3776AB?logo=python&logoColor=white)](pyproject.toml)
 [![Artifacts](https://img.shields.io/badge/Hugging%20Face-artifacts-ffcc33)](https://huggingface.co/datasets/hsafaai/supernodes-scar-artifacts)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-LossLens is a research codebase for studying which channels, neurons, and
-features matter most for model behavior. The current Python package is imported
-as `alignment` for backward compatibility.
+NodeLens is a research codebase for studying which channels, neurons, and
+features matter most for model behavior. The Python package is imported as
+`nodelens`.
 
 The repository supports two related workflows:
 
@@ -47,10 +47,10 @@ LLM backends through Hugging Face causal language models.
 ## Installation
 
 ```bash
-git clone https://github.com/KempnerInstitute/alignment.git
-cd alignment
+git clone https://github.com/KempnerInstitute/nodelens.git
+cd nodelens
 conda env create -f environment.yml
-conda activate alignment
+conda activate nodelens
 pip install -e .
 ```
 
@@ -87,7 +87,7 @@ python projects/supernodes_scar/scripts/verify_hf_artifacts.py \
 ## Paper Releases
 
 Paper-specific release material lives under `projects/`. Reusable library code
-stays in `src/alignment`, while each project folder records the exact configs,
+stays in `src/nodelens`, while each project folder records the exact configs,
 artifact layout, reproducibility notes, and release checklist for a paper.
 
 Current project:
@@ -112,7 +112,7 @@ Derived artifacts for this project are staged on Hugging Face:
 ## Repository Layout
 
 ```text
-alignment/
+nodelens/
 |-- configs/
 |   |-- prune_llm/          # LLM and SCAR configs
 |   |-- vision_prune/       # Vision pruning configs
@@ -121,7 +121,7 @@ alignment/
 |-- scripts/
 |   |-- run_experiment.py   # Main experiment entry point
 |   `-- run_analysis.py     # Post-hoc analysis
-|-- src/alignment/
+|-- src/nodelens/
 |   |-- analysis/           # Visualization, clustering, cascade analysis
 |   |-- experiments/        # Experiment classes
 |   |-- metrics/            # Importance metrics

RELEASE.md

@@ -5,7 +5,7 @@ draft files, cluster paths, logs, or model weights.
 
 ## Before Tagging
 
-- Confirm that paper-facing code lives in `src/alignment/` and
+- Confirm that paper-facing code lives in `src/nodelens/` and
   `projects/supernodes_scar/`.
 - Confirm that private draft material under `drafts/` is not tracked for the
   public release.
@@ -19,7 +19,7 @@ draft files, cluster paths, logs, or model weights.
 
 ```bash
 python -m pip install -e .
-PYTHONPATH=src python -c "import alignment; print(alignment.__version__)"
+PYTHONPATH=src python -c "import nodelens; print(nodelens.__version__)"
 pytest tests/unit -q
 cd docs && make html
 ```

configs/README.md

@@ -1,44 +1,70 @@
 # Configuration Files
 
-## Structure
+NodeLens experiments are driven by YAML configs. The same runner is used for
+small examples, vision pruning studies, and LLM supernode/SCAR experiments:
 
+```bash
+python scripts/run_experiment.py --config path/to/config.yaml
 ```
+
+The Python package is imported as `nodelens`.
+
+## Directory Map
+
+```text
 configs/
-├── template.yaml              # Complete template with all options
-├── unified_template.yaml      # Unified format template
-├── vision_prune/              # Vision model pruning configs
-|   ├── resnet18_cifar10_full.yaml
-|   ├── resnet18_cifar10_unified.yaml  # Unified format version
-|   ├── resnet50_imagenet100.yaml
-|   ├── vgg16_cifar10_full.yaml
-|   └── mobilenetv2_cifar10_full.yaml
-├── prune_llm/                 # LLM pruning configs
-|   ├── llama3_8b_full.yaml
-|   ├── llama3_8b_unified.yaml  # Unified format version
-|   ├── llama2_7b_full.yaml
-|   ├── mistral_7b_full.yaml
-|   └── qwen2_7b_full.yaml
-└── examples/                  # Example configs
-    ├── mnist_basic.yaml
-    ├── resnet_pruning.yaml
-    └── llm_alignment.yaml
+|-- template.yaml              # Full legacy-format reference
+|-- unified_template.yaml      # Unified-format reference
+|-- examples/                  # Small runnable examples and smoke tests
+|-- vision_prune/              # Vision clustering, halo, and channel pruning
+`-- prune_llm/                 # LLM supernode, SCAR, and paper-scale configs
 ```
 
-## Usage
+Large private sweep grids are not kept in the public config tree. Public
+release material for a paper lives under `projects/<project_name>/`; reusable
+experiment configs live here.
+
+## Which Config Should I Use?
+
+| Goal | Start with |
+|------|------------|
+| Quick install check on MNIST | `configs/examples/mnist_basic.yaml` |
+| Small vision pruning example | `configs/examples/resnet_pruning.yaml` |
+| Vision metric clustering and halo analysis | `configs/vision_prune/resnet18_cifar10_unified.yaml` |
+| Larger vision pruning benchmark | `configs/vision_prune/resnet50_imagenet100_unified.yaml` |
+| Minimal LLM supernode example | `configs/examples/llm_alignment.yaml` |
+| Main 8B LLM SCAR suite | `configs/prune_llm/llama3_8b_unified.yaml` |
+| Cross-model 7B/8B LLM checks | `configs/prune_llm/{llama2,mistral,qwen2}_7b_unified.yaml` |
+| 70B mechanism check | `configs/prune_llm/llama3_70b_scale_mechanism.yaml` |
+| 70B structured pruning curves | `configs/prune_llm/llama3_70b_scale_pruning_curves.yaml` |
+| OLMo checkpoint trajectory | `configs/prune_llm/olmo2_7b_ckpt_template.yaml` |
+
+## Experiment Types
+
+| Type | Used for | Typical configs |
+|------|----------|-----------------|
+| `alignment_analysis` | General activation, alignment, and pruning analysis for small models | `configs/examples/*.yaml` |
+| `cluster_analysis` | Vision channel metrics, metric-space clustering, halo analysis, cascade tests, and structured pruning | `configs/vision_prune/*.yaml` |
+| `llm_alignment` | Hugging Face causal LMs, SCAR loss-proxy metrics, supernodes, halos, perplexity, and LLM structured pruning | `configs/prune_llm/*.yaml` |
+| `vision_synergy` | Older focused vision synergy experiments | `configs/examples/vision_synergy.yaml` |
+
+## Common Commands
 
 ```bash
-python scripts/run_experiment.py --config configs/cluster_analysis/resnet18_cifar10_full.yaml
-python scripts/run_experiment.py --config configs/paper/llama3_8b_full.yaml
-python scripts/run_experiment.py --config configs/examples/resnet_pruning.yaml
-```
+# Quick smoke test
+python scripts/run_experiment.py --config configs/examples/mnist_basic.yaml
 
-## Experiment Types
+# Vision clustering and pruning
+python scripts/run_experiment.py --config configs/vision_prune/resnet18_cifar10_unified.yaml
+
+# LLM supernode and SCAR analysis
+python scripts/run_experiment.py --config configs/prune_llm/llama3_8b_unified.yaml
 
-| Type | Description |
-|------|-------------|
-| `alignment_analysis` | General alignment metrics |
-| `llm_alignment` | LLM supernode/SCAR analysis |
-| `cluster_analysis` | Metric-space clustering with halos |
+# Override output location without editing the YAML
+python scripts/run_experiment.py \
+  --config configs/prune_llm/llama3_8b_unified.yaml \
+  --base-output-dir /path/to/results
+```
 
 ## Configuration Blocks
 
@@ -55,6 +81,10 @@ python scripts/run_experiment.py --config configs/examples/resnet_pruning.yaml
 | `pruning` | Strategy, sparsity_levels, scoring |
 | `llm` | LLM-specific: scar_metrics, evaluate_perplexity |
 
+Not every block is used by every experiment type. Vision configs usually use
+`clustering`, `halo_analysis`, and `cascade_analysis`; LLM configs usually use
+`supernode`, `halo_analysis`, `llm`, and `pruning`.
+
 ## Metrics
 
 Available metrics for `metrics.enabled`:
@@ -95,24 +125,32 @@ cascade_analysis:
   n_remove_per_cluster: 5
 ```
 
-## LLM Configuration
+## Minimal LLM Configuration
 
 ```yaml
-experiment_type: llm_alignment
+experiment:
+  type: "llm_alignment"
 
-model_config:
+model:
+  name: "hf_causal_lm"
   model_id: "meta-llama/Llama-3.1-8B"
-  torch_dtype: "bfloat16"
+  dtype: "bfloat16"
 
-do_scar_metrics: true
-scar_num_samples: 100
+metrics:
+  scar:
+    enabled: true
+    num_samples: 64
+    max_length: 512
 
 supernode:
   enabled: true
   core_fraction: 0.01
   protect_core: true
 ```
 
+LLM configs require access to the model provider, enough GPU memory, and the
+right license acceptance for gated models.
+
 ## Unified Configuration Format
 
 The framework supports a **unified configuration format** that works consistently
@@ -190,7 +228,7 @@ output:
 ### Loading Unified Configs
 
 ```python
-from alignment.configs import load_unified_config
+from nodelens.configs import load_unified_config
 
 # Works with both old and unified formats!
 config = load_unified_config("configs/vision_prune/resnet18_cifar10_unified.yaml")

configs/examples/alexnet_pruning.yaml

@@ -17,7 +17,7 @@ model:
 # ImageNet dataset path on Kempner cluster
 dataset:
   name: "imagenet"
-  data_path: "/n/holylfs06/LABS/kempner_shared/Everyone/testbed/vision/imagenet_1k"
+  data_path: "/path/to/datasets/imagenet_1k"
   batch_size: 128
   num_workers: 4
 

configs/examples/llama3_extended_analysis.yaml

@@ -8,7 +8,8 @@
 # 3. Cross-layer redundancy (redundancy with previous layer)
 # 4. Layer transition efficiency (new information per layer)
 #
-# Based on theoretical framework in drafts/alignment_notes/alignment_red.tex
+# Use this as a heavier LLM analysis example after the smaller llm_alignment
+# example is working in your environment.
 # ============================================================================
 
 experiment:

configs/examples/resnet_pruning.yaml

@@ -16,10 +16,10 @@ model:
 
 # Dataset options:
 #   - cifar10/cifar100: ./data (auto-downloads, but ResNet expects 224x224)
-#   - imagenet: /n/holylfs06/LABS/kempner_shared/Everyone/testbed/vision/imagenet_1k
+#   - imagenet: /path/to/datasets/imagenet_1k
 dataset:
   name: "imagenet"
-  data_path: "/n/holylfs06/LABS/kempner_shared/Everyone/testbed/vision/imagenet_1k"
+  data_path: "/path/to/datasets/imagenet_1k"
   batch_size: 128
   num_workers: 4