ci: publish commit-addressed alpha releases of the Python SDK

[miguelg719]

Stacked on #2786 (TypeScript alphas). Retarget to main once that merges.

Why

#2786 restores <next>-alpha-<sha> npm releases on every push. This gives the Python SDK the equivalent channel.

PyPI rejects local versions (+<sha>) and PEP 440 only allows digits in a .devN segment, so the commit can't be carried in the version. The idiomatic analogue is a developmental pre-release: 4.0.3a0.dev<N>.

• a0 marks the alpha channel — sorts below the 4.0.3 it precedes and is hidden from pip install stagehand unless --pre is passed (same role as npm's alpha dist-tag).
• N = commit count on main, so successive pushes order correctly and re-running the workflow on the same commit is idempotent (PyPI rejects the duplicate rather than minting a second build).
• The existing stagehand-python@<version> git tag maps a build back to its commit.

What

• scripts/release/python-alpha-version.ts (+ tests) — after changeset version --snapshot, reads the Python proxy package.json; if it got a snapshot version there's something unreleased, so rewrite pyproject.toml to <base>a0.dev<N>. Otherwise should-publish=false. --check mode doesn't write.
• justfile — _version-python-alpha: changeset version --snapshot → apply alpha version → uv lock.
• publish-python.yml — new alpha boolean input; when set, runs just _version-python-alpha between just install and just build. Everything downstream (version read, wheel/sdist smoke tests, uv publish --trusted-publishing, git tag) is unchanged and reused. Checkout is now fetch-depth: 0 for the commit count.
• release.yml — python-alpha-status + publish-python-alpha jobs, mirroring the stable python-release-status + publish-python pair.

Verified locally

With a throwaway changeset: snapshot → should-publish=true version=4.0.3a0.dev1451, uv lock updates cleanly, uv build produces stagehand-4.0.3a0.dev1451-py3-none-any.whl + sdist, and packaging confirms 4.0.2 < 4.0.3a0.dev1451 < 4.0.3 with is_prerelease=True. pnpm exec vitest run scripts → 66/66.

Things to be aware of

• Trusted publishing is keyed on the workflow file + pypi environment, both reused here, so no PyPI config change is needed. If the pypi environment has required reviewers, every alpha will wait for approval — worth checking before merge.
• Dev builds accumulate on the PyPI project page forever (numpy et al. use a separate nightly index for this reason). Acceptable for now; flagging it.
• No changeset — CI/release infra only.

---

Summary by cubic

Publishes commit-addressed Python SDK alphas as PEP 440 developmental releases. Previously we only shipped stable versions; CI now publishes <next>a0.dev<N> when a changesets snapshot exists, ordered by commit count and requiring --pre to install stagehand (AP-2885).

• Adds scripts/release/python-alpha-version.ts (+ tests) to map snapshot versions (<next>-alpha-<sha>) to PEP 440, rewrite pyproject.toml, and support --check; outputs should-publish and version.

• Extends reusable publish-python.yml with an alpha input; applies the version via just _version-python-alpha, checks out with fetch-depth: 0, and reuses trusted publishing.

• Adds python-alpha-status and publish-python-alpha jobs in release.yml to gate alpha publishing on snapshot presence and reuse the publish workflow.

• Rollout: Reuses the existing pypi environment and trusted publishing; required reviewers will gate each alpha. Install with pip install --pre stagehand; dev builds will accumulate on PyPI.

^{Written for commit 8c2e573. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8c2e573

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant GHA as GitHub Actions
    participant GIT as Git
    participant PNPM as pnpm
    participant CS as changeset CLI
    participant SCRIPT as scripts/release/python-alpha-version.ts
    participant PYDIR as packages/sdk-python (pyproject.toml)
    participant UPL as uv lock/build
    participant PYPI as PyPI

    Note over GHA,PYPI: Python SDK Alpha Release Flow (per push)

    GHA->>GIT: checkout repo (fetch-depth: 0)

    GIT-->>GHA: full history (for commit count)

    GHA->>PNPM: pnpm install --frozen-lockfile

    GHA->>CS: changeset version --snapshot

    CS-->>GHA: snapshot versions written to package.json (e.g., 4.0.3-alpha-<sha>)

    GHA->>SCRIPT: pnpm exec tsx python-alpha-version.ts --check

    SCRIPT->>PYDIR: read package.json version

    alt snapshot present (should-publish=true)
        SCRIPT->>SCRIPT: compute commit count via git rev-list --count HEAD

        SCRIPT->>SCRIPT: pythonAlphaVersion(snapshot, count) → "4.0.3a0.dev1451"

        SCRIPT-->>GHA: should-publish=true, version=4.0.3a0.dev<N>

        GHA->>PNPM: just _version-python-alpha

        PNPM->>CS: changeset version --snapshot (re-run)

        PNPM->>SCRIPT: pnpm exec tsx python-alpha-version.ts

        SCRIPT->>PYDIR: read pyproject.toml

        SCRIPT->>PYDIR: write updated pyproject.toml with alpha version

        SCRIPT-->>PNPM: done

        PNPM->>UPL: uv lock (update lockfile)

        PNPM->>UPL: uv build

        UPL-->>GHA: .whl + .tar.gz

        GHA->>GHA: smoke test wheel/sdist

        GHA->>PYPI: uv publish --trusted-publishing

        PYPI-->>GHA: package published as stagehand-4.0.3a0.dev<N>.whl

        GHA->>GIT: tag stagehand-python@4.0.3a0.dev<N>

    else no snapshot (should-publish=false)
        SCRIPT-->>GHA: should-publish=false

        Note over GHA: skip alpha publishing
    end

    Note over PYPI: Available via `pip install --pre stagehand`
    Note over PYPI: Sorts below stable 4.0.3, above 4.0.2

Loading

_{Re-trigger cubic}