Quick Start

Getting Started

Get TokenPrint running with a real model trace in under five minutes. This guide assumes you have already completed Installation.

Step 1 — Start the backend

terminal (tab 1)

cd backend
source .venv/bin/activate
python -m uvicorn app.main:app --app-dir . --port 8000 --reload

Wait until you see Application startup complete and the model has finished loading. The first run downloads the model (~1 GB) — subsequent runs start in seconds.

Step 2 — Start the frontend

terminal (tab 2)

cd frontend
npm run dev

Open http://localhost:3000. You should see the TokenPrint shell with the 3D canvas loading.

Step 3 — Explore the architecture

The default view is Architecture mode. The 3D canvas shows a point cloud of all 290 tensors in the Qwen2.5-0.5B-Instruct model. Each point represents one tensor; the Y-axis encodes layer depth and the X-axis encodes tensor kind (embedding, attention projections, MLP, norm).

Click any point to open the Tensor Inspector in the right panel — it shows the tensor name, shape, dtype, and parameter count.

Step 4 — Run a generation trace

Click Generation in the top navigation bar. The default prompt (“The cat sat on the mat.”) is pre-loaded. Click Generate to start a real forward pass. The 3D model begins animating: each lit component represents the currently executing operation.

Tip

Use the speed slider in the bottom transport bar to slow down the animation and inspect individual operations. Press the layer-skip button to jump to the next transformer layer.

Step 5 — Run a walkthrough

Click Walkthrough. TokenPrint runs a full POST /analyze call on the example sentence and generates a 7-chapter interactive explanation. Each chapter shows real numbers from that forward pass — attention weights, embedding distances, logit lens values.