Installation

Getting Started

TokenPrint has two components: a FastAPI + PyTorch backend that runs model forward passes and a Next.js frontend that renders the 3D visualization. Both must be running simultaneously for full functionality.

Prerequisites

Requirement	Version	Notes
Python	3.11 or 3.12	Required for the backend
Node.js	20.9+	Required for the frontend
Hardware	Any	macOS (Apple Silicon / Intel), Linux, or Windows. CUDA, MPS, or CPU fallback.
Disk space	~2 GB	~1 GB for the Qwen model cache + dependencies

Quick start — the launcher

The simplest path is the supported launcher, which checks prerequisites, creates the Python environment, installs frontend dependencies, downloads the model, and starts both services:

bash

python3 scripts/start.py
# Python 3.11/3.12 · Node 20.9+
# Optional:  --check (verify prereqs), --smoke (real generation check),
#            --model MODEL, --revision REVISION, --fresh (reinstall)

Manual setup is documented below.

Backend setup

terminal

cd backend
python3 -m venv .venv --system-site-packages
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Optional: GGUF execution support
pip install -r requirements-gguf.txt

# Start the API server with auto-reload
python -m uvicorn app.main:app --app-dir . --port 8000 --reload

On first startup, the backend automatically downloads Qwen/Qwen2.5-0.5B-Instruct (~1 GB) into the local HuggingFace cache and initializes all model hooks. Subsequent startups are fast.

Note

The backend uses eager attention by default for maximum compatibility. On machines with CUDA or MPS, PyTorch will automatically select the appropriate device.

Verify the backend is running

bash

curl http://localhost:8000/health
# {"status":"ok","model_loaded":true}

Frontend setup

terminal

cd frontend
npm install
npm run dev

Navigate to http://localhost:3000. The frontend automatically connects to the backend at http://localhost:8000.

Warning

The frontend requires the backend to be running to load PyTorch model data. Without the backend, GGUF drag-and-drop (Architecture mode) and the Browser GPT-2 engine (Generation mode) still work client-side — see Browser GPT-2.

Frontend-only mode (no Python required)

You can use TokenPrint without any backend at all:

Architecture mode — drag a .gguf file onto the 3D canvas. The browser parses the binary header client-side using a TypeScript GGUF parser.
Generation — switch the engine to Browser GPT-2. It downloads a pinned Xenova/gpt2 model once (~500 MB, browser-cached) and runs real greedy generation via WebGPU or WASM. No server required.

Walkthrough and Debugger modes require the backend with a PyTorch model loaded.