Sudharsanselvaraj/Token-Print

TokenPrint is a 3D visual debugger for transformers. Load a real model, run a real forward pass, and inspect attention, RoPE, the KV cache and the residual stream as they happen.

Live site  |  Get started  |  Docs  |  Wiki  |  Roadmap  |  Discord

_{Watch the full-quality demo (.mp4)}

Requires Python 3.11 or 3.12 and Node 20.9+.

git clone https://github.com/Sudharsanselvaraj/Token-Print.git
cd Token-Print
python3 scripts/start.py

The launcher installs dependencies, downloads Qwen2.5-0.5B-Instruct with progress, starts the backend and frontend, and waits until the model is ready. Then open http://localhost:3000.

No GPU or no time? Choose Try a recorded demo on the home page to replay a real trace offline. Stuck on setup? Ask in the Discord or see local setup and troubleshooting.

# backend (Apple MPS, CUDA or CPU fallback)
cd backend && python3 -m venv .venv --system-site-packages
source .venv/bin/activate && pip install -r requirements.txt
python -m uvicorn app.main:app --app-dir . --port 8000

# frontend
cd frontend && npm install && npm run dev   # http://localhost:3000

• Every number is real. No Math.random, no placeholder tensors. Each value traces to named_parameters(), a real forward pass, or the GGUF header, and CI fails if fake data reaches app code. Values are tagged REAL, DERIVED, CONCEPTUAL or SIMULATION.
• Grouped-query attention you can see. 14 query heads and 2 KV groups, rendered as geometry clustered exactly that way.
• A debugger, not just a viewer. Breakpoints, watch expressions, activation ablation with before/after diff, logit lens, induction-head lab, and trace record, replay and branching.
• Three ways to run. Python backend, quantized GGUF, or GPT-2 in your browser through WebGPU and ONNX.
• Cited, not hand-waved. Click RoPE, SwiGLU, RMSNorm, GQA or an induction-head pair and get the primary source.
• Private. GGUF files are parsed client-side. Nothing is uploaded.

Qwen 2.5 runs live by default. Llama 2/3/3.2, Gemma, Mistral/Mixtral, DeepSeek (including MoE), Phi and GPT-2/Pythia load as GGUF, and any local .gguf works. GPT-2 also runs fully in the browser. Per-family notes are in the wiki; to add one, see the developer guide.

• GET /architecture reports 494,032,768 parameters on live Qwen, the exact sum of all 290 real tensors.
• The op catalog lists 243 ops in true forward order, matching the actual module graph.
• Five independent verification scripts and a CI regression gate back this up: docs/verification.md.

Known limits, stated plainly:

• Quantized GGUF inference is real, but llama.cpp exposes no per-layer activations, so layer lighting is disabled there instead of faked.
• Attention weight is not causal proof. It is a signal, not evidence the model needed that token (details).
• Per-layer timings are unsynchronized wall-clock on MPS and CUDA, and are badged PROXY · NOT MS when unbacked.
• Browser inference currently covers GPT-2 on desktop WebGPU with greedy decoding.

If you find a wrong number, that is a top-priority bug.

Architecture | API reference | Visual mapping | GGUF format | Browser inference | Experiments | Development | Deployment | Roadmap

Questions, bug reports, shared traces and feature ideas are all welcome in the Discord.

First-timers are welcome. Pick a task from GOOD_FIRST_ISSUES.md or the open issues, read CONTRIBUTING.md, and open a PR. Working examples to copy from are in docs/contributor-examples.md. Say hello in the Discord first if you want a hand choosing.

The one rule for every change: every number shown must be real.

_{Every person who has contributed to Token-Print. Thank you.}

MIT © Sudharsan Selvaraj. If TokenPrint helps you, you can support the project.

_{Back to top}