feat(python-sdk): pure-Python bootstrap on PyPI fetches native wheels from GH Releases

After v3.2.0 stopped publishing native wheels to PyPI (PR #44, GH
Releases is the canonical host), `pip install a3s-code` was broken on
every platform except cp310 macOS arm64 (the one wheel that snuck into
PyPI before the 10 GB project cap kicked in).

This commit restores `pip install a3s-code` by adding a tiny
pure-Python bootstrap package — also named `a3s-code` — that on first
`import a3s_code` downloads the matching native wheel for the current
interpreter and platform, verifies its sha256 against the release
manifest, extracts the compiled `_native` extension into a per-user
cache, and registers it as `sys.modules["a3s_code._native"]`.
Subsequent imports use the cache; cold start is one download per
(version, platform, interpreter) triple.

New package
- sdk/python-bootstrap/ — setuptools-built pure-Python wheel
  (a3s_code-X.Y.Z-py3-none-any.whl) and matching sdist.
  - src/a3s_code/__init__.py — calls ensure_native_loaded() then
    `from ._native import *`.
  - src/a3s_code/_bootstrap.py — wheel-name resolver, downloader,
    sha256 verifier, extension loader. Knobs: A3S_CODE_CACHE_DIR,
    A3S_CODE_RELEASES_BASE_URL, A3S_CODE_SKIP_HASH_CHECK.
  - tests/test_bootstrap.py — 15 unit tests (filename resolution,
    cache dir, sha256 mismatch, idempotency, manifest fallback) plus
    one live download test gated on A3S_CODE_BOOTSTRAP_LIVE=1.
  - README documenting install model and overrides.

Workflow
- publish-python-bootstrap.yml — runs bootstrap unit tests, builds
  wheel + sdist, twine check, twine upload on tag push.
- release.yml — adds the bootstrap publish job; runs after
  publish-python (which produces the GH Release the bootstrap points
  at) and gates github-release on both.

Release plumbing
- scripts/check_release_versions.sh now validates the bootstrap
  pyproject.toml and the runtime __version__ in _bootstrap.py — they
  must equal the core version so the bootstrap finds the matching GH
  Release tag.
- release.sh bumps both in lockstep with the other version files.
- README + sdk/python README rewritten to advertise pip install
  a3s-code again and explain the cache.

Bumps core / Node SDK / Python SDK from 3.2.0 to 3.2.1 since the
bootstrap is a user-facing addition. CHANGELOG [3.2.1] entry
documents the new package + rationale.

End-to-end verified locally: built the wheel, installed into a fresh
venv, ran `import a3s_code` with __version__ patched to 3.2.0 so the
bootstrap points at the real GH Release; Agent.create succeeded.

Author: claude

.github/workflows/publish-python-bootstrap.yml

@@ -0,0 +1,41 @@
+name: Publish Python Bootstrap
+
+# Builds and publishes the pure-Python `a3s-code` bootstrap shim to PyPI.
+# The shim is tiny (no native code) so it sails under PyPI's per-project
+# size cap. On first `import a3s_code` it downloads the matching native
+# wheel for the user's platform from this repo's GitHub Releases.
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish Python Bootstrap to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Run bootstrap unit tests
+        working-directory: sdk/python-bootstrap
+        run: python -m unittest tests.test_bootstrap -v
+
+      - name: Build wheel + sdist
+        run: python -m build --wheel --sdist sdk/python-bootstrap
+
+      - name: Twine check
+        run: python -m twine check sdk/python-bootstrap/dist/*
+
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_NATIVE_TOKEN }}
+        run: python -m twine upload --skip-existing sdk/python-bootstrap/dist/*

.github/workflows/release.yml

@@ -119,20 +119,32 @@ jobs:
     secrets: inherit
 
   # ───────────────────────────────────────────────
-  # Build and publish Python native SDK (reusable)
+  # Build native Python wheels and attach to GitHub Release (reusable).
+  # No longer pushes to PyPI — the per-project size cap made that
+  # impractical. GH Release is the canonical wheel host.
   # ───────────────────────────────────────────────
   publish-python:
-    name: Python SDK
+    name: Python SDK (native wheels → GH Release)
     needs: [ci, ci-windows]
     uses: ./.github/workflows/publish-python.yml
     secrets: inherit
 
+  # ───────────────────────────────────────────────
+  # Publish the pure-Python bootstrap to PyPI so `pip install a3s-code`
+  # still works. Needs the native wheels to be on GH Release first.
+  # ───────────────────────────────────────────────
+  publish-python-bootstrap:
+    name: Python SDK (bootstrap → PyPI)
+    needs: [publish-python]
+    uses: ./.github/workflows/publish-python-bootstrap.yml
+    secrets: inherit
+
   # ───────────────────────────────────────────────
   # Create GitHub Release
   # ───────────────────────────────────────────────
   github-release:
     name: GitHub Release
-    needs: [publish-crate, publish-node, publish-python]
+    needs: [publish-crate, publish-node, publish-python, publish-python-bootstrap]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.1] - 2026-05-24
+
+### Added
+
+- Python SDK: small pure-Python **bootstrap** shim published to PyPI as
+  `a3s-code`. On first `import a3s_code` it downloads the matching
+  native wheel for the current interpreter/platform from this repo's
+  GitHub Releases, verifies the wheel's sha256 against the release
+  manifest, extracts the compiled `_native` extension into
+  `~/.cache/a3s-code/<version>/`, and registers it as
+  `sys.modules["a3s_code._native"]`. Subsequent imports use the cache.
+  Source under `sdk/python-bootstrap/`.
+  - Environment knobs: `A3S_CODE_CACHE_DIR`, `A3S_CODE_RELEASES_BASE_URL`,
+    `A3S_CODE_SKIP_HASH_CHECK`.
+  - 15 unit tests + 1 live download test gated on
+    `A3S_CODE_BOOTSTRAP_LIVE=1`.
+  - New workflow `publish-python-bootstrap.yml`, wired after
+    `publish-python` in `release.yml`.
+- `scripts/check_release_versions.sh` now also validates the bootstrap
+  package version and the runtime `__version__` literal.
+- `release.sh` now bumps the bootstrap version in lockstep with the
+  core release.
+
+### Fixed
+
+- `pip install a3s-code` works again from v3.2.1, restored after v3.2.0
+  could only push a single wheel to PyPI under the quota cap.
+
 ## [3.2.0] - 2026-05-24
 
 ### Added

Cargo.lock

@@ -81,21 +81,22 @@ Full migration notes are in [CHANGELOG.md](./CHANGELOG.md).
 ## Install
 
 ```bash
+# Python
+pip install a3s-code
+
 # Node.js
 npm install @a3s-lab/code
-
-# Python (from v3.2.0; pick the wheel for your interpreter/platform)
-pip install \
-  https://github.com/AI45Lab/Code/releases/download/v3.2.0/a3s_code-3.2.0-cp312-cp312-manylinux_2_28_x86_64.whl
 ```
 
 Rust users can depend on `a3s-code-core`.
 
-Python wheels are hosted on [GitHub Releases](https://github.com/AI45Lab/Code/releases)
-from v3.2.0 onwards — the project grew past PyPI's per-project storage
-quota for binary distributions. Each release ships a
-`python-native-manifest.json` with sha256 hashes for every wheel.
-Versions up to 3.1.0 remain installable via `pip install a3s-code==3.1.0`.
+From v3.2.1 onwards the PyPI `a3s-code` package is a small pure-Python
+bootstrap. On first `import a3s_code` it downloads the matching native
+wheel from [GitHub Releases](https://github.com/AI45Lab/Code/releases),
+verifies the wheel's sha256 against the release manifest, and caches the
+compiled extension under `~/.cache/a3s-code/<version>/`. Subsequent
+imports use the cache. The split exists because the full native-wheel
+matrix grew past PyPI's per-project storage cap.
 
 ---
 

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "3.2.0"
+version = "3.2.1"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/Cargo.toml

@@ -101,6 +101,17 @@ echo "  Updating sdk/python/pyproject.toml..."
 sed -i.bak "s/^version = \".*\"/version = \"${VERSION}\"/" sdk/python/pyproject.toml
 rm -f sdk/python/pyproject.toml.bak
 
+# Update Python bootstrap shim (pyproject.toml + runtime __version__).
+# Must stay in lockstep with core so the bootstrap fetches the matching
+# native wheel from GH Releases on first import.
+echo "  Updating sdk/python-bootstrap/pyproject.toml..."
+sed -i.bak "s/^version = \".*\"/version = \"${VERSION}\"/" sdk/python-bootstrap/pyproject.toml
+rm -f sdk/python-bootstrap/pyproject.toml.bak
+
+echo "  Updating sdk/python-bootstrap/src/a3s_code/_bootstrap.py..."
+sed -i.bak "s/^__version__ = \".*\"/__version__ = \"${VERSION}\"/" sdk/python-bootstrap/src/a3s_code/_bootstrap.py
+rm -f sdk/python-bootstrap/src/a3s_code/_bootstrap.py.bak
+
 echo "  Updating Node package lockfiles..."
 update_node_lockfile sdk/node/package-lock.json
 update_node_lockfile sdk/node/examples/package-lock.json

release.sh

@@ -97,6 +97,14 @@ def check_node_lockfile(path):
                 check_equal(f"{path} package {key or '<root>'} optionalDependency {name}", value)
 
 
+def check_bootstrap_runtime_version(path):
+    match = re.search(r'^__version__\s*=\s*"([^"]+)"', read(path), re.MULTILINE)
+    if not match:
+        fail(f"{path}: missing __version__ literal")
+        return
+    check_equal(f"{path} __version__", match.group(1))
+
+
 if not expected:
     expected = first_manifest_version("core/Cargo.toml") or ""
 
@@ -110,6 +118,8 @@ check_core_dependency("sdk/node/Cargo.toml")
 check_core_dependency("sdk/python/Cargo.toml")
 check_package_json("sdk/node/package.json")
 check_pyproject("sdk/python/pyproject.toml")
+check_pyproject("sdk/python-bootstrap/pyproject.toml")
+check_bootstrap_runtime_version("sdk/python-bootstrap/src/a3s_code/_bootstrap.py")
 check_cargo_lock("Cargo.lock")
 check_node_lockfile("sdk/node/package-lock.json")
 check_node_lockfile("sdk/node/examples/package-lock.json")

scripts/check_release_versions.sh

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-node"
-version = "3.2.0"
+version = "3.2.1"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"
@@ -11,7 +11,7 @@ description = "A3S Code Node.js bindings - Native addon via napi-rs"
 crate-type = ["cdylib"]
 
 [dependencies]
-a3s-code-core = { version = "3.2.0", path = "../../core", features = ["ahp", "s3"] }
+a3s-code-core = { version = "3.2.1", path = "../../core", features = ["ahp", "s3"] }
 napi = { version = "2", features = ["async", "napi6", "serde-json"] }
 napi-derive = "2"
 tokio = { version = "1.35", features = ["full"] }