fusedtok 0.1.0__tar.gz

fusedtok-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build-and-test:
+    # GPU runners are not available on free plans; this job verifies that the
+    # project compiles with nvcc and that CPU-side tests pass. CUDA test cases
+    # detect the absence of a GPU and skip themselves (pytest skipif marker).
+    runs-on: ubuntu-latest
+    container:
+      image: nvidia/cuda:12.4.1-devel-ubuntu22.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install build dependencies
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends python3-dev python3-pip
+          pip3 install --no-cache-dir pybind11 pytest numpy cmake ninja
+
+      - name: Configure
+        run: >
+          cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+          -DCMAKE_PREFIX_PATH="$(python3 -m pybind11 --cmakedir)"
+
+      - name: Build
+        run: cmake --build build
+
+      - name: Test (CPU; CUDA cases auto-skip without a GPU)
+        run: |
+          export PYTHONPATH=$PWD/build
+          python3 -m pytest tests -q

fusedtok-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC): no API tokens or passwords anywhere.
+# The pending publisher configured on PyPI side:
+#   project=fusedtok  owner=Hai-Wenxiang  repo=fusedtok
+#   workflow=publish.yml  environment=(none)
+#
+# Two jobs: the CUDA build must run inside a container, but
+# pypa/gh-action-pypi-publish is a Docker action and Docker actions cannot
+# execute within container jobs - so artifacts are passed through the
+# workflow artifact store to a plain ubuntu-latest publishing job (the
+# pattern documented by PyPA for containerized builds).
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: nvidia/cuda:12.4.1-devel-ubuntu22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install build dependencies
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends python3-dev python3-pip python3.10-venv
+          # patchelf via pip: ubuntu22.04's apt copy (0.14.3) is older than
+          # auditwheel's required >= 0.14.5
+          pip3 install --no-cache-dir build auditwheel patchelf
+
+      - name: Build sdist and wheel
+        run: python3 -m build --outdir dist
+
+      - name: Repair wheel to manylinux (PyPI rejects bare linux tags)
+        run: |
+          auditwheel show dist/*.whl
+          auditwheel repair dist/*.whl -w wheelhouse/
+          rm -f dist/*.whl
+          mv wheelhouse/*.whl dist/
+
+      - name: List artifacts
+        run: ls -lh dist/
+
+      - name: Store artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 5
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC).
+      id-token: write
+      contents: read
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Verify project is live
+        run: |
+          sleep 10
+          curl -fsS "https://pypi.org/pypi/fusedtok/json" | head -c 200 || true

fusedtok-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Build
+build/
+out/
+*.obj
+*.exe
+*.dll
+*.lib
+*.exp
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/
+
+# IDE
+.vs/
+.vscode/
+.idea/
+
+# CUDA
+*.cubin
+*.fatbin
+
+# CMake
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+
+# OS
+Thumbs.db
+Desktop.ini
+
+build2/

fusedtok-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-08-23
+
+First public release.
+
+### Added
+- Operators: RMSNorm (+fused residual), LayerNorm (affine), RoPE
+  (interleaved and NeoX layouts, kv-cache `pos_offset`), SwiGLU, row-wise
+  softmax, SiLU / GeLU (erf + tanh) / ReLU / Tanh / Sigmoid, elementwise
+  add / mul, temperature scaling, repetition penalty, top-k, top-p
+  (nucleus), argmax.
+- Three execution paths per op: CPU reference (ground truth, no GPU
+  needed), staged CUDA (numpy in / numpy out), and **zero-copy CUDA**
+  (kernels run directly in torch device buffers via `data_ptr()`).
+- `pip install .` via scikit-build-core; sm_80/sm_86 cubins plus
+  compute_86 PTX for JIT on newer architectures.
+- Optimized kernels: block-reduced norms/softmax, float4-vectorized
+  elementwise, exp2f/sincosf RoPE frequencies (6.2x vs eager), parallel
+  packed-key selection for top-k/top-p/argmax with deterministic ties.
+- Benchmark suite (`benchmarks/bench.py`) with CUDA-event timing and
+  chart; bilingual README; CI on GitHub Actions (build + CPU tests).

fusedtok-0.1.0/CMakeLists.txt

@@ -0,0 +1,56 @@
+cmake_minimum_required(VERSION 3.24)
+project(fusedtok VERSION 0.1.0 LANGUAGES CXX CUDA)
+
+# C++17 for host code; CUDA follows via nvcc default
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Target GPU architectures: native sm_80 (A100) and sm_86 (RTX 30) cubins
+# plus a compute_86 PTX embed so newer architectures (RTX 40/50, sm_89+) can
+# JIT the kernels with their drivers.
+# Set unconditionally (not only when undefined): build frontends may inject
+# an empty CMAKE_CUDA_ARCHITECTURES that would otherwise fall back to the
+# compiler default. Override with -DFUSEDTOK_CUDA_ARCHITECTURES="..." if
+# you need something else.
+set(FUSEDTOK_CUDA_ARCHITECTURES "80-real;86-real;86-virtual" CACHE STRING
+    "CUDA architectures fusedtok compiles for")
+set(CMAKE_CUDA_ARCHITECTURES ${FUSEDTOK_CUDA_ARCHITECTURES})
+
+find_package(CUDAToolkit REQUIRED)
+# pybind11 provided by pip; pass its cmake dir via CMAKE_PREFIX_PATH
+# (or it is injected by scikit-build-core during packaged builds)
+find_package(pybind11 CONFIG REQUIRED)
+
+# The compiled extension module loaded as `fusedtok._fusedtok`.
+# Under scikit-build-core it installs into the python/fusedtok package dir.
+pybind11_add_module(_fusedtok
+    src/fusedtok.cu
+    src/rmsnorm.cu
+    src/rope.cu
+    src/activations.cu
+    src/softmax.cu
+    src/layernorm.cu
+    src/topk.cu
+    src/sampling.cu
+    src/bindings.cpp)
+target_include_directories(_fusedtok PRIVATE include src)
+# Static CUDA runtime: the wheel then carries no libcudart.so dependency,
+# letting auditwheel tag it manylinux (PyPI rejects bare linux_x86_64 tags).
+target_link_libraries(_fusedtok PRIVATE CUDA::cudart_static)
+
+if(SKBUILD)
+    install(TARGETS _fusedtok LIBRARY DESTINATION fusedtok)
+endif()
+
+# Suppress C4819 (codepage warning) on MSVC hosts, and force the conforming
+# preprocessor (CCCL / cooperative_groups headers refuse the traditional one).
+# Options must be routed per-language: nvcc rejects a bare "/Zc:..." or
+# "/wd4819" on a CUDA source as a stray input file, so CUDA sources get them
+# wrapped in -Xcompiler, CXX sources get them directly.
+if(MSVC)
+    target_compile_options(_fusedtok PRIVATE
+        "$<$<COMPILE_LANGUAGE:CUDA>:-Xcompiler=/Zc:preprocessor>"
+        "$<$<COMPILE_LANGUAGE:CUDA>:-Xcompiler=/wd4819>"
+        "$<$<COMPILE_LANGUAGE:CXX>:/Zc:preprocessor>"
+        "$<$<COMPILE_LANGUAGE:CXX>:/wd4819>")
+endif()

fusedtok-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,66 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces (issues, PRs,
+discussions) and also applies when an individual is officially representing
+the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement via the
+repository's maintainer contact. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of
+the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
+available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

fusedtok-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to fusedtok
+
+Thanks for your interest in improving fusedtok!
+
+## Ways to help
+
+- **Bug reports**: open an issue with the op name, shapes, dtypes, GPU model,
+  driver/CUDA version, and a minimal reproducer. Include the CPU vs GPU
+  mismatch if it is a numerical issue.
+- **Performance ideas**: profiles, Nsight Compute reports, or concrete kernel
+  suggestions are extremely welcome. The bar for merging a faster kernel is
+  that the full test suite stays green.
+- **New operators**: check the roadmap in the README first; avoid operators
+  that duplicate PyTorch one-to-one without a fusion or sampling benefit.
+
+## Development setup
+
+```bash
+git clone https://github.com/Hai-Wenxiang/fusedtok.git
+cd fusedtok
+pip install -e .            # or: cmake -S . -B build -G Ninja && cmake --build build
+pip install pytest torch    # torch optional but recommended for the CUDA tests
+pytest tests -q
+```
+
+Requirements: CUDA Toolkit >= 12.0, a CUDA GPU of compute capability 8.0+
+(Ampere or newer). CPU-only machines can still run the CPU reference tests —
+CUDA cases skip automatically.
+
+## Rules of the road
+
+1. **Every kernel ships with a CPU reference implementation** and parity
+   tests (multiple shapes, edge cases, error paths, GPU-vs-CPU comparison).
+2. **Determinism where promised**: selection ops (top-k / top-p / argmax)
+   resolve ties toward the earliest index; keep that invariant.
+3. **Error contract**: shape problems raise `ValueError`, CUDA problems
+   raise `RuntimeError` (mapped from `std::invalid_argument` /
+   `std::runtime_error` in C++).
+4. **Comments in English**, explaining *why* (design constraints, GPU
+   micro-arch reasons), not *what*.
+5. Benchmarks use CUDA events, never wall clock (WDDM makes host timing
+   on Windows meaningless).
+6. Keep the CI green: `ubuntu-latest` + CUDA container build and CPU tests
+   run on every push.
+
+## Pull requests
+
+- One logical change per PR, with tests and README updates in the same PR.
+- PRs are merged only with passing CI and maintainer review.
+- By contributing you agree your contributions are licensed under the MIT
+  license (see [LICENSE](LICENSE)).

fusedtok-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hai-Wenxiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fusedtok-0.1.0/NOTICES.md

@@ -0,0 +1,21 @@
+# Third-party notices
+
+fusedtok is MIT licensed (see LICENSE). This product builds on:
+
+## pybind11
+
+Licensed under the BSD-style license found in
+https://github.com/pybind/pybind11/blob/master/LICENSE.
+Used at build time to generate the Python bindings.
+
+## NVIDIA CUDA Toolkit
+
+The compiled extension links the CUDA Runtime (cudart) and is built with the
+NVIDIA CUDA Compiler. Use of the CUDA Toolkit is governed by NVIDIA's
+software license: https://developer.nvidia.com/cuda-toolkit-software-license-agreement
+
+## Optional runtime dependencies
+
+- NumPy (BSD-3-Clause) - array interface for the staged path.
+- PyTorch (BSD-3-Clause) - optional; used for the zero-copy CUDA path and in
+  the benchmark suite.

fusedtok-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.2
+Name: fusedtok
+Version: 0.1.0
+Summary: Fused CUDA kernels for LLM inference: RMSNorm, RoPE, SwiGLU, sampling ops, with zero-copy torch support
+Keywords: cuda,llm,inference,kernels,deep-learning,pytorch
+Author: Hai-Wenxiang
+License: MIT License
+         
+         Copyright (c) 2026 Hai-Wenxiang
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+         
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Project-URL: Homepage, https://github.com/Hai-Wenxiang/fusedtok
+Project-URL: Repository, https://github.com/Hai-Wenxiang/fusedtok
+Project-URL: Issues, https://github.com/Hai-Wenxiang/fusedtok/issues
+Project-URL: Changelog, https://github.com/Hai-Wenxiang/fusedtok/releases
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: torch
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Description-Content-Type: text/markdown
+
+# fusedtok
+
+[![CI](https://github.com/Hai-Wenxiang/fusedtok/actions/workflows/ci.yml/badge.svg)](https://github.com/Hai-Wenxiang/fusedtok/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/fusedtok.svg)](https://pypi.org/project/fusedtok/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+**Fused CUDA kernels for LLM inference** — RMSNorm / RoPE / SwiGLU and friends,
+with **zero-copy torch tensor support**: up to **6.2x faster than PyTorch eager**
+(RoPE, RTX 3060, see [Benchmarks](#benchmarks)).
+
+**中文文档请看 [README_zh.md](README_zh.md)** | English below.
+
+## Why
+
+LLM inference frameworks launch many small, memory-bound operators per token. Each launch
+round-trips through global memory. `fusedtok` fuses them into single kernels to cut memory
+traffic and launch overhead.
+
+## Operators
+
+| Status | Kernel | Notes |
+|---|---|---|
+| ✅ | RMSNorm (+residual) | LLaMA/Qwen style, fused residual add |
+| ✅ | LayerNorm | with affine |
+| ✅ | RoPE | interleaved **and** NeoX layouts, kv-cache `pos_offset` |
+| ✅ | SwiGLU | fused MLP activation |
+| ✅ | Softmax (row-wise) | numerically stable |
+| ✅ | SiLU / GeLU / GeLU-tanh / ReLU / Tanh / Sigmoid | elementwise |
+| ✅ | add / mul | elementwise binary (fused add+residual pattern) |
+| ✅ | top-k / top-p (nucleus) | deterministic ties |
+| ✅ | argmax / temperature | greedy decoding helpers |
+| ✅ | repetition penalty | CTRL-style, applied to sampled token ids |
+| ⏳ | INT8/FP8 quantized path | planned v0.3 |
+
+## Install
+
+```bash
+pip install fusedtok
+```
+
+Prebuilt Linux x86_64 wheels (manylinux, built with CUDA 12.4) are on PyPI.
+On Windows (or any platform without a matching wheel) pip builds from
+source automatically:
+
+```bash
+git clone https://github.com/Hai-Wenxiang/fusedtok.git
+cd fusedtok
+pip install .
+```
+
+**Requirements:**
+
+- NVIDIA GPU of **RTX 30 series (Ampere) or newer** — e.g. RTX 3060/3090, RTX 4080, RTX 5090, A100, H100
+- CUDA Toolkit >= 12.0
+- A C++17 compiler (MSVC on Windows, GCC/Clang on Linux); Python 3.10+
+
+<details>
+<summary>What is "compute capability"? (click to expand)</summary>
+
+Compute capability is NVIDIA's version number for a GPU architecture generation — not a
+performance score. CUDA code must be compiled for a specific architecture to run on it.
+The wheel builds native cubins for compute capability 8.0 (A100) and 8.6 (RTX 30) plus a
+compute_86 PTX fallback, so Ampere runs natively and newer architectures (RTX 40/50, ...)
+JIT the PTX with their driver.
+
+| Compute capability | Architecture | Example GPUs |
+|---|---|---|
+| 7.5 | Turing | GTX 16xx, RTX 20xx (not supported) |
+| 8.0 / 8.6 | Ampere | A100, RTX 30xx |
+| 8.9 | Ada | RTX 40xx (via PTX) |
+| 9.0 | Hopper | H100 (via PTX) |
+| 12.0 | Blackwell | RTX 50xx (via PTX) |
+
+Check yours: run `nvidia-smi` to see your GPU model, then look it up at
+https://developer.nvidia.com/cuda-gpus
+
+</details>
+
+## Usage
+
+numpy in / numpy out, or torch in / torch out — including **zero-copy CUDA**:
+kernels read and write torch device buffers directly via `data_ptr()`, with
+no staging copies and no host synchronization.
+
+```python
+import numpy as np
+import torch
+import fusedtok
+
+x = np.random.randn(4, 1024).astype(np.float32)
+w = np.random.rand(1024).astype(np.float32)
+
+# CPU reference implementation (ground truth, runs anywhere)
+y = fusedtok.rmsnorm(x, w, eps=1e-6)
+
+# staged CUDA: copies to GPU, runs kernel, copies back
+y = fusedtok.rmsnorm(x, w, cuda=True)
+
+# zero-copy CUDA with torch tensors: kernels run in torch's own buffers,
+# stream-ordered with other torch operations
+xt, wt = torch.from_numpy(x).cuda(), torch.from_numpy(w).cuda()
+yt = fusedtok.rmsnorm(xt, wt)          # -> CUDA torch tensor
+
+# RoPE with kv-cache position offset, NeoX (LLaMA-HF) layout
+q = torch.randn(1, 4096, device="cuda")          # new token only
+q_rot, k_rot = fusedtok.rope(q, k=None, pos_offset=1023, neox=True)
+
+# sampling side
+logits = fusedtok.repetition_penalty(logits, sampled_ids, penalty=1.1)
+values, indices = fusedtok.topk(logits, k=50)
+```
+
+Every function accepts float32 numpy arrays or torch tensors (other dtypes
+are converted with a copy) and returns float32 outputs of the same family.
+CUDA torch tensors select the zero-copy path automatically.
+
+See `examples/demo.py` for a runnable tour of every operator.
+
+## Correctness
+
+Every kernel ships with a CPU reference implementation and element-wise parity tests
+(pytest). Tests run on machines without a GPU (CUDA cases skip automatically).
+
+## Benchmarks
+
+RTX 3060 (sm_86), float32, zero-copy torch tensors, CUDA-event timing, vs the
+equivalent PyTorch eager expressions (full data: `docs/benchmark_results.json`,
+reproduce with `python benchmarks/bench.py`):
+
+| Op | Shape | fusedtok | PyTorch eager | Speedup |
+|---|---|---:|---:|---:|
+| RoPE NeoX (q+k) | [2048×4096] | 416 µs | 2570 µs | **6.2x** |
+| RMSNorm (+residual) | [1024×4096] | 260 µs | 538 µs | **2.1x** |
+| SwiGLU | [1024×4096] | 153 µs | 257 µs | **1.7x** |
+| LayerNorm | [1024×4096] | 168 µs | 162 µs | ~1.0x |
+| SiLU | [1024×4096] | 105 µs | 112 µs | ~1.0x |
+| Softmax | [1024×4096] | 159 µs | 115 µs | 0.7x |
+| argmax | [131072] | 36 µs | 46 µs | **1.3x** |
+| top-k (k=50) | [131072] | 168 µs | 129 µs | 0.8x |
+
+![fusedtok vs PyTorch eager](docs/benchmark_rt3060.png)
+
+Fusions win big (RoPE / RMSNorm / SwiGLU) because eager mode round-trips
+intermediate tensors through global memory. Pure memory-bound elementwise ops
+run at the same ~330-500 GB/s as PyTorch's tuned kernels (silu, gelu, add ≈
+parity). Softmax and top-k remain behind PyTorch's CUB-based kernels —
+honest numbers, on the v0.2 roadmap.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (test rules,
+error contract, determinism invariants). Quick start:
+
+```bash
+# Windows: run inside a VS developer prompt (vcvars64)
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+# from repo root: PYTHONPATH picks up the built module, conftest.py adds python/
+$env:PYTHONPATH = "$PWD/build"        # Windows
+PYTHONPATH=$PWD/build                 # Linux
+python -m pytest tests -q
+python benchmarks/bench.py            # GPU benchmark + chart
+```
+
+Windows / Linux. Windows uses MSVC via nvcc; CI builds and runs the CPU test
+suite on every push.
+
+## Roadmap
+
+- v0.2: bf16 support, radix-select top-k/top-p (CUB-class speed), fused
+  sampling (softmax+top-p+draw in one pass), CUDA graph-friendly batching
+- v0.3: INT8/FP8 quantized paths, block-size autotuning
+- v0.4+: lightweight fused attention; prebuilt wheels on PyPI
+
+## Community
+
+- [Contributing guide](CONTRIBUTING.md) — setup, rules of the road, PR process
+- [Code of conduct](CODE_OF_CONDUCT.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+MIT — see [LICENSE](LICENSE). Third-party notices: [NOTICES.md](NOTICES.md).