Python package: compile and launch API (DLPack / PyTorch-friendly)

[tetsuo-cpp]

Summary

Ship a Python package that compiles WarpForth sources to PTX and launches kernels against CUDA buffers (numpy/DLPack/torch), so users do not hand-roll PyCUDA wrappers.

Motivation

Adoption currently requires:

1. Build C++ tools
2. Run warpforthc
3. Custom host code (demo/warpforth.py with PyCUDA) or the C++ runner

The GPT-2 demo works but is not a reusable product surface. A small warpforth Python API would make the compiler usable from ML workflows and is the natural layer above the JSON runner redesign (#50).

Proposed API (sketch)

import warpforth as wf
import torch

kernel = wf.compile("attention.forth", arch="sm_80")
# or wf.compile_source(src)

q, k, v, o = ...  # torch CUDA tensors
kernel.launch(
    grid=(seq_len, 1, 1),
    block=(threads, 1, 1),
    params={"Q": q, "K": k, "V": v, "O": o, "SEQ_LEN": seq_len, "HEAD_DIM": head_dim},
)

Features

• Discover params from header or emitted metadata (see metadata issue)
• Accept torch tensors / DLPack / cuda-python buffers without host round-trips
• Optional: compile from string; cache PTX by source hash
• Errors: compile diagnostics and launch failures as Python exceptions

Packaging

• pip install / uv add with optional CUDA extra
• May wrap warpforthc binary or embed via bindings; start with subprocess + cuda-python

Acceptance criteria

• Package builds with project pyproject.toml (or documented extra)
• Compile + launch path works for at least one array kernel end-to-end
• Demo GPT-2 path can use the package instead of bespoke warpforth.py
• README quickstart for Python users
• Coordinates with Replace warpforth-runner C++ CLI with Python cuda-python + JSON protocol #50 protocol rather than inventing a second ad-hoc CLI

Related

• Runner redesign (Replace warpforth-runner C++ CLI with Python cuda-python + JSON protocol #50)
• Kernel metadata emission (separate)
• GPT-2 demo (GPT-2 interactive inference demo with WarpForth attention #46 closed)