Sudharsanselvaraj/Token-Print
Sudharsanselvaraj/Token-Print has 226 GitHub stars and 45 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 23:54 UTC. Last push 2026-11-15.
What you can do
- 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.
Measured star growth
- in 24h
- 0
- in 7 days
- Update delayed
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Interactive 3D visualization platform for exploring transformer architectures, tensors, and real-time LLM inference.
AIREADME.md
Original
Stop reading architecture diagrams. Watch your model think.
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)
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.
Manual setup
# 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 tonamed_parameters(), a real forward pass, or the GGUF header, and CI fails if fake data reaches app code. Values are taggedREAL,DERIVED,CONCEPTUALorSIMULATION. - 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 /architecturereports 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.cppexposes 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 MSwhen 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.
Join the TokenPrint CommunityDiscord · Q&A · Show and Tell · Shared Traces |
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.
Every person who has contributed to Token-Print. Thank you.
License
MIT © Sudharsan Selvaraj. If TokenPrint helps you, you can support the project.