Vector Lab · a research instrument
Vectorscope
The internal geometry of a language model, made visible.
Vectorscope loads an open-weight model locally and shows you its embeddings, hidden states, attention patterns and generation dynamics as geometry. It also extracts and applies grammar steering vectors. One Next.js frontend, one FastAPI backend, nothing cloud-mediated.
01 · About
Treat the vector medium as something you can read.
Vectorscope is a workbench for the critical examination of open-weight large language models. It loads one model into memory on your own machine and gives you twelve operations across three analytical postures: inspect the static matrices (embeddings, projection head, weight comparison, attention), trace a sequence through the pipeline (token trajectory, layer probe, full trace, generation vector, manifold formation), and critique the geometry through intervention (contrastive activation extraction and forward-pass steering).
What makes it different from mechanistic interpretability dashboards is the orientation. The vector space is treated as a medium with a grain, not as a diagnostic surface. Where tools like TransformerLens and BertViz are instruments for alignment research, Vectorscope is an instrument for reading what a model is: its geometry, its training residues, its ideological affordances.
Only open-weight models. Commercial APIs do not expose embeddings, hidden states or attention; the internal geometry Vectorscope visualises simply does not exist through those endpoints. Vectorscope is free software under the GPL-3.0-or-later licence and part of the Vector Lab.
Each tagged release is archived on Zenodo and assigned a version DOI; the badge resolves to the latest. To cite: Berry, D. M. (2026). Vectorscope: a workbench for inspecting the vector medium of open-weight language models. Zenodo.
02 · Modes
Three postures: Inspect, Trace, Critique.
Each image links to a full-resolution screenshot. The views below use GPT-2 124M, which is small, ungated and fast enough to run on CPU.
The matrices themselves
The input embedding table, the output projection head, their alignment, and per-head attention. The static objects a model carries before any input arrives. Mean norms, cosine structure, nearest-neighbour lookups token by token.
The pipeline, moving
Send a sequence through the model and instrument the forward pass. Watch one token travel the residual stream from layer to layer, probe hidden states at a chosen depth, stream the whole pipeline as NDJSON, or scrub autoregressive generation one step at a time. The Manifold Formation view plays layer-by-layer PCA as animation.
Steering vectors, in and out
The Critique group implements contrastive activation addition. Phase 1 extracts a steering vector from paired positive and negative prompts. Phase 2 adds that vector back into the residual stream at a chosen layer, scaled by a coefficient, and lets you compare the baseline and steered completions side by side.
03 · A worked moment
Nearest neighbours of "king" in GPT-2.
Load GPT-2 124M, open Inspect, Embedding Table, type king into the nearest-neighbours box and press return. The panel lists the ten tokens closest to king in the input embedding matrix, by cosine distance, with their similarities.
The ranking reads like a thesaurus with a weighted history: the regal cluster first, then the Middle Eastern honorifics the WebText corpus happens to carry, then an English surname with a capital K. GPT-2's input embeddings are the trace of that corpus, viewed one token at a time.
Nearest to " king" · cosine similarity · GPT-2 124M
04 · Setup
Install, run, load a model.
Vectorscope is two local processes: a Python backend that holds the model and a Next.js frontend that talks to it. Models cache to ~/.cache/huggingface/; subsequent loads are near-instant.
Prerequisites
- Python 3.9 or newer. Node.js 18 or newer. Git.
- Disk. GPT-2 is roughly 500 MB. Llama 3.2 1B is 2.5 GB. Mistral 7B is 14 GB.
- Memory. GPT-2 runs in 8 GB; 1B to 3B models want 16 GB; 7B wants 24 GB of unified memory on Apple Silicon or equivalent.
Clone and run
git clone https://github.com/vector-lab-tools/vectorscope.git cd vectorscope # backend, first terminal cd backend python3 -m venv .venv source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 pip install --upgrade pip pip install -r requirements.txt python main.py # Uvicorn on http://127.0.0.1:8000 # frontend, second terminal, from the project root npm install npm run dev # open http://localhost:3000
In the top-right of the header the device indicator reads mps, cuda or cpu when the frontend has reached the backend. Click the model name in the header, pick GPT-2 124M, hit Load, then try Inspect, Embedding Table as a smoke test.
Hugging Face keys for the gated models
This is the one setup step that trips every new user. You only need it for Llama and Mistral. GPT-2 and Qwen3 are ungated and work without an account.
Ungated no key
GPT-2 (124M to 1.5B) and Qwen3 (0.6B to 4B). Load directly from the model picker. Nothing to configure.
Hugging Face account free
Sign up at huggingface.co/join. Confirm the email, downloads fail silently on an unconfirmed account.
Access token read scope
Create at huggingface.co/settings/tokens, prefix hf_. Read scope is enough. Copy it on creation, Hugging Face will not show it again.
Model licence per model
Open Llama 3.2 1B or Mistral 7B v0.3 signed in, submit the short access form. Approval is usually within minutes. The page will say "You have been granted access".
Log in from the backend's venv
The token has to be visible to the Python process that will download the weights, which means the backend's activated virtual environment, not another shell. Stop the backend, then, in the same terminal with the venv still active:
pip install huggingface_hub huggingface-cli login # paste the hf_ token when prompted # Login successful. Your token has been saved to ~/.cache/huggingface/token python main.py # restart the backend
Answer n to "Add token as git credential" unless you want it in your git config. In Vectorscope, open the model picker, select Llama 3.2 1B or Mistral 7B, and click Load. First load downloads the weights, subsequent loads are near-instant.
HTTP 403 on download. Three real causes, in order of frequency. One: the licence has not been granted yet on your account; re-open the model page while signed in and check for "You have been granted access". Two: the token is not visible to the backend; cat ~/.cache/huggingface/token should print the key, and if it does not, run huggingface-cli login inside the backend's activated venv rather than another shell. Three: the token has been revoked; create a new one and run login again. A 401 instead of 403 means the token is syntactically invalid; regenerate it.
Common failures
- Frontend says "Backend unreachable". Backend is not running or bound to another port. curl http://localhost:8000/status should return JSON.
- ModuleNotFoundError: torch. The venv is not activated. source backend/.venv/bin/activate and retry.
- EADDRINUSE on port 3000. Another Next dev server is running. Use PORT=3001 npm run dev.
- Device reports cpu on Apple Silicon. Your PyTorch build is CPU-only. Reinstall from pytorch.org with the macOS wheels.
- Out of memory. Pick a smaller preset. GPT-2 in 8 GB, 1B to 3B in 16 GB, 7B in 24 GB of unified memory.