The Problem

Large language models waste compute on redundant matrix‑multiplications. qwenTPU embeds a weight‑stationary TPU inside Qwen3.5 weights, so the model can perform exact 16×16 or 32×32 MACs without extra hardware or extra training.

What This Does

qwenTPU implements a data‑flow array that reads a Gated DeltaNet head and turns each multi‑hot read into a full reduction. The core logic lives in the qwentpu/ directory (20 Python files). demo.py launches a small demo that runs the TPU layer on real tokens; bench_driver.py collects performance counters. The static site in docs/ visualises the architecture and the trace; it is built from docs/site/app.js and docs/site/index.html.

How It Is Wired

Entry point – demo.py (root). demo.py imports qwentpu.core (main module) and calls run_tpu() passing a pre‑loaded Qwen3.5 model. run_tpu() pulls the delta‑net weight matrix from the model, constructs a DataflowArray instance, and streams token traces through DataflowArray.step(). DataflowArray.step() performs the one‑hot write, updates the partial‑sum state, and returns the result. The TPU’s state is stored in qwentpu/state.py; the adder tree logic resides in qwentpu/adder.py. The trace is fed from qwentpu/trace.py, which reads a JSON trace produced by Qwen3.5. The only external effect is writing the final token logits to stdout and optionally recording stats to bench_driver.py.

The repository has no central hub: each file owns a single responsibility. core.py is the widest blast radius – it orchestrates the whole flow and imports all sub‑modules. state.py and adder.py are tightly coupled; changing one requires touching the other. The static docs site (docs/site/) is independent of the TPU logic; its only touchpoint is the demo.py entry point for generating trace data.

How To Use It

Setup

# Clone
git clone https://github.com/moses-y/qwentpu
cd qwentpu

# Install Python deps
pip install -e .          # pyproject.toml defines the package

The repo uses pyproject.toml; no lockfile is present, so reproducibility depends on the current package index.

Configuration

No environment variables are required. Weights are loaded from the Qwen3.5 checkpoint path passed on the command line.

Running it

python demo.py --model-path /path/to/qwen3.5-0.8b --trace-file trace.json

demo.py will stream the trace through the TPU and print logits. For benchmarking, run:

python bench_driver.py --model-path /path/to/qwen3.5-0.8b --trace-file trace.json

Real‑World Use

A production system that needs deterministic, integer‑exact matrix‑multiplication can embed qwenTPU as a lightweight layer. Example:

from qwentpu.core import run_tpu
model = load_qwen3_5("qwen3.5-0.8b")
trace = load_trace("trace.json")
logits = run_tpu(model, trace)

The output logits can then be fed back into the language model pipeline.

Code Health & Issues

  • Medium / SDLC – No CI/CD pipeline – no .github/ or other CI config, so automated testing is missing.
  • Low / SDLC – No lockfile – pyproject.toml lacks a lockfile; builds may drift over time.
  • Low – No Dockerfile – containerization not provided.
  • Low – No comprehensive README commands – install instructions are inferred, not documented.

No other static analysis findings were reported.

The Bottom Line

qwenTPU demonstrates a feasible way to embed a TPU into a pretrained model’s weights, achieving exact integer arithmetic without extra hardware. The code base is small and focused but lacks CI and reproducible builds, which limits rapid iteration. It is suitable for research or prototyping where deterministic matrix‑multiplication is required, but not yet ready for production deployment.