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+	Required for the backend
Node.js	18.0+	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

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 model data. Without the backend, the 3D canvas will show a loading state. GGUF drag-and-drop works client-side without the backend.

GGUF-only mode (no Python required)

You can use the Architecture mode without a running backend by dragging a .gguf file onto the 3D canvas. The browser parses the binary header client-side using a TypeScript GGUF parser — no server required. Generation, Walkthrough, and Debugger modes require the backend.