Contributing

Reference

TokenPrint is open source. Contributions are welcome — especially fixes to the known data fidelity gaps, new model architecture support, and debugger panel improvements.

Setup

bash

git clone https://github.com/Sudharsanselvaraj/Token-Print.git
cd Token-Print

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

# Frontend
cd ../frontend
npm install
npm run dev

Before opening a PR

bash

# 1. Verify frontend data integrity
cd frontend
npm run build           # fails if Math.random found in app code

# 2. Verify backend data
cd ../backend
python3 scripts/verify_real_data.py
python3 scripts/verify_trace.py

Important

The data integrity check is enforced by npm run build. If your change introduces Math.random in application code, the build will fail. This is intentional — all numbers must be real.

Branch naming

Prefix	Use for	Example
`feat/`	New features	`feat/logit-lens-panel`
`fix/`	Bug fixes	`fix/attention-row-sum`
`docs/`	Documentation	`docs/update-api-reference`
`chore/`	Build / tooling changes	`chore/upgrade-next15`

Commit conventions

Use Conventional Commits:

text

feat(ui): add provenance badge to tensor inspector
fix(backend): correct head ablation math
docs(api): add trace replay endpoint
chore(deps): upgrade three.js to r167

PR scope

Keep PRs focused on a single issue. A PR that fixes a data fidelity bug should not also refactor unrelated components. Reviewers look at:

Does the change introduce any Math.random calls?
Are all displayed numbers still traceable to a real model output?
Does npm run build pass?
Are TypeScript errors introduced?

Good first issues

The GOOD_FIRST_ISSUES.md file has curated beginner tasks organized by difficulty, with specific files to touch and how to verify the change.