feat(packaging)!: introduce slim agentex-client + heavy agentex-sdk split

[max-parke-scale]

Currently Blocked on access to PyPi to create the new package

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.

Install command	Deps	Ships
pip install agentex-client	6	agentex/{__init__.py, _*.py, _utils/, types/, resources/, protocol/, py.typed}
pip install agentex-sdk	6 (transitive) + 31 ADK	only agentex/lib/*; depends on agentex-client

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-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-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-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-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-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_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-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-client package name; add AGENTEX_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-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_client-*.whl '*.dist-info/METADATA' | grep ^Name
# Name: agentex-client
unzip -p dist/agentex_client-*.whl '*.dist-info/METADATA' | grep -cE "^Requires-Dist:" | grep -v "extra =="
# 6
unzip -l dist/agentex_client-*.whl | grep -c "agentex/lib"
# 0  (lib excluded)
unzip -l dist/agentex_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-client"
# Requires-Dist: agentex-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_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-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 existing agentex-sdk wheel into two namespace-sharing packages: a slim REST client (agentex-client, 6 deps, Python ≥ 3.11) and the heavy ADK overlay (agentex-sdk, 31 deps, Python ≥ 3.12). Existing consumers see no change because the heavy wheel depends on the slim transitively.

• pyproject.toml / adk/pyproject.toml: root package renamed to agentex-client and stripped to 6 deps; new adk/ workspace member carries all ADK deps plus a hatchling build hook that force-includes ../src/agentex/lib per-file (pruning tests), with a 320-file floor guard to catch a broken walk.
• Release plumbing: bin/publish-pypi builds both wheels with --wheel (required for the cross-directory force-include) and publishes slim-first; --check-url makes the workflow idempotent under release-please's per-component double-trigger; scripts/check-slim-deps adds a CI guardrail that fails if Stainless regenerates the root dep list with ADK deps.
• ⚠️ PR description / checklist drift: the PR title and "Required maintainer follow-ups" section consistently say agentex-sdk-client and AGENTEX_SDK_CLIENT_PYPI_TOKEN, but the actual code uses agentex-client and AGENTEX_CLIENT_PYPI_TOKEN throughout. Following the checklist as written would claim the wrong PyPI name and add a secret the publish pipeline never reads — the slim publish would silently fall back to PYPI_TOKEN (the heavy's token), which fails if that token is project-scoped. The checklist should be updated to agentex-client / AGENTEX_CLIENT_PYPI_TOKEN before maintainers act on it.

Confidence Score: 5/5

Safe to merge once the PR description checklist is corrected; all code paths are internally consistent and prior review concerns have been addressed.

The packaging split is well-structured: wheel disjointness is enforced by both the root exclude and the ADK build hook's force_include, the file-count floor in hatch_build.py provides a safety net, and the publish script correctly sequences slim-before-heavy with --check-url idempotency. The PR description's checklist uses different names than the code, but that discrepancy lives only in the PR description text, not in any committed file.

The PR description's Required maintainer follow-ups checklist should be reviewed and corrected before any PyPI or secrets work begins.

Important Files Changed

Filename	Overview
pyproject.toml	Renamed from agentex-sdk to agentex-client; slim 6-dep list; adds uv workspace and sources for dev; excludes src/agentex/lib/** from wheel. Correct and consistent with the split.
adk/pyproject.toml	New pyproject for the heavy agentex-sdk wheel; depends on agentex-client>=0.12.0 (floor-only, acknowledged), requires Python >= 3.12, uses hatchling + custom build hook. Sdist purposely gutted. Correct.
adk/hatch_build.py	New build hook that walks ../src/agentex/lib, maps each file via force_include, prunes test files, enforces a 320-file floor guard. Logic is sound.
bin/publish-pypi	Rewrites publish to build both wheels with --wheel then publish slim before heavy. --check-url makes the workflow idempotent under double-trigger. Addresses both prior review concerns.
scripts/check-slim-deps	New CI guardrail checking root pyproject.toml has exactly the 6 slim deps. Uses bare python3 which may lack tomllib on pre-3.11 systems; otherwise logic is correct.
bin/check-release-environment	Extended to validate both AGENTEX_CLIENT_PYPI_TOKEN and AGENTEX_PYPI_TOKEN with PYPI_TOKEN fallback. Consistent with publish script.
release-please-config.json	Adds adk package component, moves extra-files to root package entry, enables include-component-in-tag. Tag scheme change is the expected breaking change flagged in the title.
.github/workflows/publish-pypi.yml	Adds both token env vars; PYPI_TOKEN falls back to AGENTEX_PYPI_TOKEN. Double-trigger idempotency handled via --check-url in the script. Correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[uv build --all-packages --wheel] --> B[agentex_client-*.whl\nname: agentex-client\n6 deps, Python >= 3.11]
    A --> C[agentex_sdk-*.whl\nname: agentex-sdk\n31 deps + agentex-client, Python >= 3.12]
    C -->|adk/hatch_build.py force_include| D[src/agentex/lib/**]
    B -->|pyproject.toml exclude| E[src/agentex lib excluded]
    B --> F[site-packages/agentex/\n__init__.py, _*.py\ntypes/, resources/, protocol/]
    C --> G[site-packages/agentex/lib/**]
    F & G --> H[agentex.* namespace\ndisjoint files, no conflicts]
    subgraph publish [bin/publish-pypi]
        direction LR
        P1[uv publish --check-url\nAGENTEX_CLIENT_PYPI_TOKEN\nagentex_client-*.whl] --> P2[uv publish --check-url\nAGENTEX_PYPI_TOKEN\nagentex_sdk-*.whl]
    end
    B --> P1
    C --> P2

Loading

Comments Outside Diff (1)

1. .github/workflows/publish-pypi.yml, line 8-9 (link)

   Double-publish failure on separate release events

   With include-component-in-tag: true, release-please creates two separate GitHub releases: agentex-sdk-client-v* and agentex-sdk-v*. Each triggers this workflow independently. Every invocation of bin/publish-pypi publishes both packages unconditionally, so the second triggered run will attempt to re-upload artifacts already present on PyPI. Since rye publish (via twine) exits non-zero on a 409 Conflict and the script runs with set -eux, the second workflow run will fail. Adding --skip-existing to both rye publish calls in bin/publish-pypi (or switching to twine upload --skip-existing dist/*) would make the publish script idempotent and tolerate this re-trigger.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: .github/workflows/publish-pypi.yml
   Line: 8-9
   
   Comment:
   **Double-publish failure on separate release events**
   
   With `include-component-in-tag: true`, release-please creates two separate GitHub releases: `agentex-sdk-client-v*` and `agentex-sdk-v*`. Each triggers this workflow independently. Every invocation of `bin/publish-pypi` publishes *both* packages unconditionally, so the second triggered run will attempt to re-upload artifacts already present on PyPI. Since `rye publish` (via twine) exits non-zero on a 409 Conflict and the script runs with `set -eux`, the second workflow run will fail. Adding `--skip-existing` to both `rye publish` calls in `bin/publish-pypi` (or switching to `twine upload --skip-existing dist/*`) would make the publish script idempotent and tolerate this re-trigger.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
scripts/check-slim-deps:9
`tomllib` was added to the Python standard library in 3.11. Invoking bare `python3` relies on the system Python, which may be 3.10 on older Ubuntu runners (ubuntu-22.04) or developer machines. On those systems this fails with `ModuleNotFoundError: No module named 'tomllib'`, giving a confusing CI error that hides the actual dep-drift it's meant to catch. Using `uv run python3` routes through the project-managed Python (>= 3.12 per `uv.lock`) and is always safe.

```suggestion
uv run python3 - <<'PY'
```

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

[max-parke-scale]

Fixed in cdb3a48:

• bin/publish-pypi: added --wheel to both slim and heavy rye build --clean so neither falls into rye's sdist-then-wheel-from-sdist default (which silently produces an empty heavy wheel because the unpacked sdist can't resolve adk/'s ../src/agentex/lib force-include).
• adk/pyproject.toml: dropped the malformed "/../src/agentex/lib/**" sdist entry; sdist support for the dual-package layout is deferred (CI + publish-pypi are wheel-only).

Verified locally: both wheels build with uvx pyproject-build --wheel and have disjoint contents (slim has 0 agentex/lib/* files; heavy has 347 lib/* files + no top-level client surface).

@greptile review

🤖 — posted via Claude Code

[max-parke-scale]

@greptile review

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	agentex-sdk@​0.11.9 ⏵ 0.12.0

View full report

[declan-scale]

We should monitor once this is merged into next, and see what parts of the codegen may create regressions and then create ci/cd steps to address

[declan-scale]

This will likely lead to the autogen creating merge conflicts, we will see when it merges into next

[max-parke-scale]

Agreed, will monitor - and at some point followup with splitting the repos.