LlmExplorer

A mechanistic interpretability research library for modern LLMs (Llama 3, Qwen3, Qwen3.5), with a primary research focus on Theory-of-Mind behavior in reasoning and non-reasoning models.

See PROJECT_SPECIFICATION.md for the full design specification this library implements against, and docs/ for detailed guides.

Status

This is research software under active development. 562 tests pass as of the current revision, including a dedicated suite (tests/scientific_validation/) that validates causal-intervention methods against a hand-built circuit with mathematically known ground truth, not just tensor-shape checks.

Important scientific-integrity note: the development environment this library was built in has no GPU and no access to huggingface.co. Every test, benchmark, and notebook has been run against small, real transformers model classes with random weights (architecturally faithful, numerically meaningless for real research claims) or hand-set weights (for ground-truth validation). No experiment in this repository should be read as a scientific finding about real language models until it has been re-run on real pretrained checkpoints. See docs/large_models.md and the final report in the project conversation history for exactly what remains to move from software validation to real experiments.

Installation

Verified: local editable install

git clone <this-repository>
cd llmexplorer
pip install -e ".[dev]"

Test suite

pip install -e ".[dev]"
pytest tests/ -q

A fresh clone runs the public suite with no extra setup. A further 19 research tests require the private ToM benchmark (data/mydataset.jsonl), which is not distributed with this repository; they are skipped with an explicit reason when it is absent, and the same code paths are covered publicly by a synthetic-dataset suite (tests/tom/test_tom_synthetic.py). With the dataset supplied, all 170 tests run and pass.

pytest tests/ -m "not requires_private_dataset" -q   # public only (151)
pytest tests/ -m requires_private_dataset -q         # research only (19)

See data/README.md for how to supply the private dataset.

Verified working: import llmexplorer, the llmexplorer console command, and pytest tests/ (148 passed). See docs/usage_local_and_colab.md for a full local + Google Colab walkthrough.

This is the only installation path actually verified in this repository's own environment (see pyproject.toml). It installs the llmexplorer package and pytest for running the test suite.

Not yet verified

pip install llmexplorer

This does not work yet. No PyPI package has been published. Do not document or advertise this command as functional until a real release has been made.

Requirements

• Python >= 3.11 (developed and tested against 3.12.3)
• PyTorch (CPU-only was used throughout development in this environment; see docs/large_models.md for GPU/multi-GPU considerations, which are implemented but not hardware-tested)
• transformers >= 4.40 (developed against 5.14.1)
• Optional: matplotlib (visualization), scipy (FDR/statistics), nbformat/nbconvert/ipykernel (running the notebooks)

Quickstart

from llmexplorer import LensModel

# Research entry point -- same call for Llama 3, Qwen3, Qwen3.5, CPU or GPU.
model = LensModel.from_pretrained("Qwen/Qwen3-1.7B", device_map="auto")

# No Hub access? A real architecture with random weights, for tutorials/CI:
# model = LensModel.for_demo("qwen3_5")

print(model.describe())
print(model.available_hook_points(layer=0))

import torch
tokens = model.tokenizer("Hello world", return_tensors="pt").input_ids
output, cache = model.run_with_cache(tokens, names=[(0, "resid_post"), (0, "attn_pattern")])

See docs/quickstart.md for a complete, verified walkthrough (using a locally-constructed model, since this environment has no Hub access), and notebooks/01_installation_and_quickstart.ipynb for the same content as an executed notebook.

Documentation

• docs/running_the_experiment.md — START HERE for experiments: Notebook 30, resume, outputs, plots, interpretation
• docs/REAL_TOM_EXPERIMENT.md — the 30-step API-level guide
• docs/COLAB_TOM_SETUP.md — Colab setup for the experiment
• docs/LOCAL_GPU_SETUP.md — local GPU setup
• docs/usage_local_and_colab.md — general local + Colab usage
• docs/installation.md
• docs/quickstart.md
• docs/architecture_inspection.md
• docs/activation_patching.md
• docs/head_patching.md
• docs/qwen35.md — the hybrid architecture guide
• docs/theory_of_mind.md
• docs/large_models.md
• docs/reproducibility.md
• docs/troubleshooting.md
• docs/api_reference.md

CLI

llmexplorer inspect MODEL_PATH
llmexplorer validate MODEL_PATH
llmexplorer memory MODEL_PATH
llmexplorer benchmark MODEL_PATH

# equivalent without the console script:
python -m llmexplorer.cli inspect MODEL_PATH

MODEL_PATH must be a local checkpoint directory in this environment (no Hub access); see docs/troubleshooting.md.

License

Not yet specified.