forge is not installable: the wheel contains no kernels and import fails outside the repo

[Shaurya-M002]

pip install ./forge produces a package that cannot be imported anywhere except from inside a checkout of this repository. This is the single blocker between what exists and a usable library.

Reproduced 2026-08-14:

$ uv build forge/ -o /tmp/forge_build          # builds fine
$ python -c "import zipfile; print(sorted({n.split(chr(47))[0] for n in zipfile.ZipFile(WHL).namelist()}))"
[forge, forge-0.0.1.dev1.dist-info]            # files under kernels/ : 0

$ cd /tmp && PYTHONPATH=/tmp/forge_site python -c "import forge"
  File "/tmp/forge_site/forge/kernels/rope.py", line 12, in <module>
    from kernels.rope.forge_rope_v3 import (
ModuleNotFoundError: No module named kernels

Two causes, both known:

1. forge/forge/kernels/*.py are thin re-export shims that do absolute imports of the top-level kernels package (from kernels.rope.forge_rope_v3 import ...), and kernels/ lives at the repo root, outside the distribution.
2. forge/forge/__init__.py compensates with a sys.path.insert of ../.. relative to the package file. That works from a checkout and cannot work from site-packages. Its own comment says so: "Post-hackathon clean-up: copy each kernel file into forge/kernels/ and drop this block."

The fix is that clean-up: the kernels have to live inside the distributed package. That means deciding what the package actually contains, because kernels/<name>/experiments/v1..v6/ exists to preserve the performance history and should not all ship — only the version each kernel currently dispatches to.

Suggested shape:

forge/forge/kernels/rope.py        # the real implementation, vendored
forge/forge/kernels/rmsnorm.py
...
kernels/<name>/experiments/        # stays in the repo as the research record

with the repo-root benchmarks importing from forge.kernels so there is exactly one copy of each kernel being measured and shipped. Interacts with the experiments/ sys.path collision issue — worth sequencing them together.

Until this is fixed, no release, PyPI or otherwise, is meaningful. A CI job that installs the built wheel into a clean venv and runs import forge would have caught this on day one.

[Shaurya-M002]

Fixed in #20, merged to main via #21.

The distribution is now built from the repository root across two source roots, so both import packages ship:

[tool.setuptools]
package-dir = { forge = "forge/forge", kernels = "kernels" }

No kernel source moved. The sys.path inserts inside the LoRA kernels resolve relative to __file__, so they keep working once the files are actually present. The import-hygiene cleanup stays on #3.

Verified with the exact command the README now gives, into a clean venv on a machine where the repo is not on sys.path:

$ pip install git+https://github.com/Forge-researchlab/kernel-POCs.git
$ cd /tmp && python proof.py
forge             /tmp/gitinstall/lib/python3.11/site-packages/forge
kernels.rope      /tmp/gitinstall/lib/python3.11/site-packages/kernels/rope
patched           {'fused_linear_ce': 1, 'embedding': 1, 'swiglu': 2, 'rmsnorm': 5}
cosine vs eager   0.999952
train step        loss=6.4099, backward OK
unpatch           restored

So patch, forward, backward and unpatch all work from site-packages. The sdist resolves the same modules, which is the path pip install git+ actually takes.

Two dependency bugs came out of testing a clean resolve, neither visible from inside the existing .venv, both of which would have hit every installer:

• transformers>=4.40 resolves to 5.x, which requires torch>=2.5. Against the torch<2.5 pin it does not fail loudly — it disables its own torch backend, and every AutoModel call then raises "requires the PyTorch library but it was not found". This broke the dev environment mid-change and took the suite to 0/7 until pinned <5.
• setuptools is a runtime dependency, not a build one: triton 3.0's CUDA driver imports it from triton/runtime/build.py when compiling a launcher. It sat in the original dependency list unexplained, I removed it as build-only, and every kernel import broke with ModuleNotFoundError: No module named 'setuptools'.

Guards against regression, since this failure was invisible for months: scripts/check_packages_declared.py runs in CI and fails when a package in the tree is missing from the declared list, and the structure job builds the wheel and confirms the kernel modules land in site-packages. The latter is a filesystem check rather than an import, because importing any forge submodule executes forge/__init__.py, which needs torch, and a CPU runner has none.

Two things deliberately left for #16 before any PyPI release: the top-level import name kernels is too generic for site-packages, and the vendored Unsloth baseline ships in the wheel because LoRA MLP v5/v6 import it at runtime, so attribution needs sorting.