Get started
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
For quantized GGUF execution: pip install -r backend/requirements-gguf.txt. To force CPU: TOKENPRINT_DEVICE=cpu.
Features
- 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.
Supported models
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.
Why you can trust the numbers
GET /architecture reports 494,032,768 parameters on live Qwen, the exact sum of all 290 real tensors.- The op catalog lists 219 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.
Documentation
Architecture | API reference | Visual mapping | GGUF format | Browser inference | Experiments | Development | Deployment | Roadmap
Community
Questions, bug reports, shared traces and feature ideas are all welcome in the Discord.
Contributing
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.
License
MIT © Sudharsan Selvaraj. If TokenPrint helps you, you can support the project.
