Summary

Publishes the existing agentex-sdk wheel as two namespace-sharing packages so REST-only consumers can install just the Stainless REST surface without dragging in the full ADK runtime.

The two packages contribute disjoint files to the agentex.* namespace. Existing pip install agentex-sdk consumers see no change: heavy depends on slim, so the slim deps install transitively.

Motivating consumer: packages/egp-api-backend hand-rolls a ~600-line JSON-RPC gateway today because it can't import the typed wire shapes without pulling in temporalio, fastapi, claude-agent-sdk, and 28 other deps. With this split + #371 (which moves protocol types to agentex.protocol.*), that gateway can pin agentex-sdk-client and use from agentex.protocol.acp import RPCMethod, CreateTaskParams, ....

Tracking: AGX1-292.

Note on the PR stack

This change was originally drafted as a single large PR (history visible in the force-push). On review it was clearly two distinct concerns, so it's been split:

• refactor(types): promote protocol types to agentex.protocol.* #371 — refactor only: move protocol types from agentex.lib.types.* to agentex.protocol.* with back-compat shims. Zero install-time impact.
• This PR (feat(packaging)!: introduce slim agentex-sdk-client + heavy agentex-sdk split #370) — packaging: introduce the second wheel and the release plumbing.

Reviewing them separately should be much more tractable.

Repo layout after merge

scale-agentex-python/
├── pyproject.toml                # Stainless-managed: agentex-sdk-client
│                                 # 6 deps, requires-python >= 3.11
│                                 # wheel `exclude` keeps lib/ out of the slim wheel
├── src/agentex/                  # shared source tree
│   ├── __init__.py, _*.py, _utils/, types/, resources/   # Stainless-generated
│   ├── protocol/                                          # (from #371)
│   └── lib/                                               # hand-authored ADK overlay
└── adk/                          # hand-authored — preserved via keep_files
    ├── pyproject.toml            # agentex-sdk
    │                             # depends on agentex-sdk-client>=0.12.0 (floor-only)
    │                             #          + 31 ADK deps
    │                             # requires-python >= 3.12
    │                             # wheel: force-include via hatch_build.py (below)
    ├── hatch_build.py            # hook: force-include ../src/agentex/lib, prune tests
    └── README.md

src/agentex/lib/ stays where it is — Stainless already preserves it per CONTRIBUTING.md. The slim wheel's [tool.hatch.build.targets.wheel].exclude keeps lib/ out of the slim. The heavy wheel pulls lib/ in via a hatchling build hook (adk/hatch_build.py) that force-includes ../src/agentex/lib and prunes the test files (force-include ignores exclude — hatchling #1395). Same source file, two disjoint wheels.

Python-version pins

• agentex-sdk-client: requires-python = ">= 3.11,<4". Zero 3.12-only imports in the Stainless surface.
• agentex-sdk: requires-python = ">= 3.12,<4". agentex/lib/* uses from typing import override (3.12+ stdlib) in 19 files. The combined package's prior >= 3.11 pin was de-facto broken on 3.11; this PR aligns the pin with what actually works.

Release / publish wiring

• bin/publish-pypi: publishes slim before heavy. Heavy depends on slim, so flipping the order means a slim-side failure (token, transient PyPI 5xx, name collision) aborts before we ship a heavy that pins an unreleased slim.
• bin/check-release-environment: validates both AGENTEX_SDK_CLIENT_PYPI_TOKEN and AGENTEX_PYPI_TOKEN, with legacy PYPI_TOKEN as fallback.
• .github/workflows/publish-pypi.yml: passes both token secrets to the script.
• release-please-config.json: two-package mode (. and adk/) with include-component-in-tag = true. Tag scheme changes from v0.12.0 → agentex-sdk-client-v0.12.0 / agentex-sdk-v0.12.0 — flagged with ! in the title and commit. Any downstream tooling filtering by raw v* tags will need updating.
• .release-please-manifest.json: seeds adk/ at 0.12.0 so the first release produces matched versions.
• CI build job: builds both wheels via uv build --all-packages --wheel (the --wheel flag is important — uv's sdist-then-wheel default can't resolve adk's cross-directory force-include).

Required maintainer follow-ups before this can ship

• Stainless dashboard:
  • Add adk/** to keep_files so the ADK overlay persists across codegen.
  • Reduce the dashboard's emitted dep list for root pyproject.toml to the 6 slim-base deps. (See "Risks" below — if this isn't done, every Stainless regen will silently re-add the 31 ADK deps to slim's dependencies = [...].)
• PyPI: claim the agentex-sdk-client package name; add AGENTEX_SDK_CLIENT_PYPI_TOKEN to repo secrets. agentex-sdk publishing continues using AGENTEX_PYPI_TOKEN from adk/.
• Verify: after Stainless dashboard config, trigger a Stainless regen and confirm adk/ survives and root pyproject's slim shape isn't clobbered.

Planned follow-up PRs

The post-codegen dep-list guardrail (scripts/check-slim-deps) and the requirements{,-dev}.lock regeneration — originally planned here — are now included in this PR.

• E (in scaleapi/scaleapi): migrate packages/egp-api-backend from hand-rolled JSON-RPC to typed agentex.protocol.acp shapes; pin agentex-sdk-client. ~600 lines of dict-literal construction become typed model usage.
• README split: the root README.md describes capabilities the slim doesn't ship; deferring to its own PR so this one stays focused on packaging.
• agentex.__version__ policy: release-please-config.json's extra-files updates only root _version.py, so the runtime __version__ reflects the slim only. Either lockstep-version both (recommended, since they're co-released) or add a separate agentex.lib.__version__.

Verification (local)

# Slim wheel (uv builds both workspace members into the root dist/)
uv build --wheel
unzip -p dist/agentex_sdk_client-*.whl '*.dist-info/METADATA' | grep ^Name
# Name: agentex-sdk-client
unzip -p dist/agentex_sdk_client-*.whl '*.dist-info/METADATA' | grep -cE "^Requires-Dist:" | grep -v "extra =="
# 6
unzip -l dist/agentex_sdk_client-*.whl | grep -c "agentex/lib"
# 0  (lib excluded)
unzip -l dist/agentex_sdk_client-*.whl | grep -c "agentex/protocol"
# 3  (from #371)

# Heavy wheel
uv build --package agentex-sdk --wheel
unzip -p dist/agentex_sdk-*.whl '*.dist-info/METADATA' | grep "agentex-sdk-client"
# Requires-Dist: agentex-sdk-client>=0.12.0
unzip -l dist/agentex_sdk-*.whl | awk '{print $4}' | grep "^agentex/" | grep -v "^agentex/lib"
# (empty — only lib/* in heavy)

# Dual install on Python 3.13
python3.13 -m venv /tmp/c && /tmp/c/bin/pip install \
  dist/agentex_sdk_client-*.whl dist/agentex_sdk-*.whl
/tmp/c/bin/python -c "
from agentex import Agentex                                          # slim
from agentex.protocol.acp import RPCMethod, CreateTaskParams         # slim (from #371)
from agentex.lib.utils.logging import make_logger                    # heavy
from agentex.lib.types.acp import RPCMethod as RM2                   # heavy (shim from #371)
assert RPCMethod is RM2  # shim re-exports canonical
print('OK')
"
# OK

Risks

• Stainless dashboard dep-list is more load-bearing than the wheel exclude. The slim's [tool.hatch.build.targets.wheel].exclude = ["src/agentex/lib/**"] is a hand-edit to Stainless's emitted file. Manual edits to dependencies = [...] survive Stainless 3-way merge historically (~7 confirmed examples from git log). We're betting the wheel-target exclude survives the same way. If it gets clobbered, the slim wheel would start re-including lib/ and conflict with the heavy on install. Detection: the slim-deps guardrail (scripts/check-slim-deps, run in CI) catches it. Mitigation if it happens: re-add manually or move the exclude to the Stainless dashboard if configurable.
• Tag scheme change. Downstream tooling filtering by v* tags needs to update — flagged with ! in title/commit per Conventional Commits.
• adk/ sdist support deferred. Wheels publish fine; sdist for adk/ doesn't because uv's default sdist-then-wheel flow can't resolve the cross-directory force-include. PyPI tolerates wheel-only releases; if reviewers want sdist support, options are (a) configure hatchling to copy ../src/agentex/lib into the sdist, or (b) explicitly disable sdist for adk/.
• agentex-sdk-client pin in adk/pyproject.toml is floor-only (>=0.12.0). The packages co-version and release-please can't rewrite the pin string, so any <X ceiling eventually excludes the co-versioned slim it pins. Floor-only always resolves; an exact-pin check could be added to scripts/check-slim-deps later for tighter lockstep.

Greptile Summary

This PR splits the single agentex-sdk wheel into two namespace-sharing packages: a slim agentex-sdk-client (6 deps, REST surface only) and a heavy agentex-sdk (31 ADK deps, agentex/lib/* only) that depends on the slim. Existing pip install agentex-sdk consumers see no change — the heavy pulls the slim transitively.

• Root pyproject.toml is renamed to agentex-sdk-client, drops all 31 ADK deps, and gains a [tool.uv.workspace] + exclude = [\"src/agentex/lib/**\"] to keep the slim wheel disjoint from the heavy.
• New adk/ directory ships the heavy wheel via a custom hatchling build hook (hatch_build.py) that force-includes ../src/agentex/lib per-file, with a _MIN_FILES=320 floor guard to catch a broken walk at build time rather than silently shipping an empty wheel.
• Release / CI plumbing wires up two-component release-please, dual-token publish with --check-url idempotency, and a scripts/check-slim-deps CI guardrail that fails if Stainless codegen ever accidentally re-adds ADK deps to the slim's dependency list.

Important Files Changed

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Source["Source Tree (shared)"]
        SRC["src/agentex/\n__init__.py, _*.py\ntypes/, resources/\nprotocol/"]
        LIB["src/agentex/lib/\n(ADK overlay)"]
    end

    subgraph SlimWheel["agentex-sdk-client wheel"]
        SLIM["agentex/* REST surface\n6 deps, requires-python ge 3.11"]
    end

    subgraph HeavyWheel["agentex-sdk wheel"]
        HOOK["hatch_build.py\n(force-include lib/, prune tests)"]
        HEAVY["agentex/lib/*\n31 ADK deps, requires-python ge 3.12"]
    end

    subgraph Release["Release Pipeline"]
        RP["release-please (two-component tags)"]
        PUB["bin/publish-pypi\nuv build --all-packages --wheel\nuv publish --check-url"]
        CHECK["scripts/check-slim-deps (CI guardrail)"]
    end

    SRC --> SlimWheel
    LIB --> HOOK --> HEAVY
    SlimWheel -->|Requires-Dist| HeavyWheel
    RP --> PUB
    CHECK --> PUB

_{Reviews (10): Last reviewed commit: "feat(packaging)!: split agentex-sdk into..." | Re-trigger Greptile}