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 agentex-client (6 REST-only deps, Python ≥ 3.11) and the existing agentex-sdk (31 ADK deps, Python ≥ 3.12) that depends on the slim. The change is motivated by consumers who need the typed wire shapes without pulling in temporalio, fastapi, and the full ADK runtime.

• New adk/ workspace member: adk/pyproject.toml + adk/hatch_build.py define agentex-sdk; the custom hatchling hook walks ../src/agentex/lib, builds a per-file force_include map (bypassing the cross-directory limitation), and enforces a minimum-file floor to catch broken walks. The root pyproject.toml is renamed to agentex-client with the 31 ADK deps stripped out.
• Release plumbing overhaul: bin/publish-pypi migrated to uv publish --check-url (idempotent re-publish), ordered slim-first; bin/check-release-environment validates both tokens; release-please-config.json enters two-package mode with include-component-in-tag: true (tag scheme changes from v* to agentex-client-v* / agentex-sdk-v*).
• CI updates: uv build --all-packages --wheel and uv sync --all-packages propagated throughout CI; scripts/check-slim-deps added as a lint-step guardrail against Stainless re-adding ADK deps to the slim.

Confidence Score: 5/5

Safe to merge; all functional packaging and publish logic is correct. The noted validation gap and minor help-text inconsistency are non-blocking.

The core packaging split is well-designed: disjoint wheel contents enforced by both the slim exclude and the heavy's bypass-selection+force_include, the hatchling hook's minimum-file floor prevents silent empty builds, and publish ordering (slim before heavy) is correct. Required maintainer follow-ups are clearly tracked and the PR is intentionally gated on PyPI access.

bin/check-release-environment — the slim-token check is bypassed in GHA context when AGENTEX_PYPI_TOKEN is set; worth hardening once AGENTEX_CLIENT_PYPI_TOKEN is added to secrets.

Important Files Changed

Filename	Overview
bin/publish-pypi	Rewrites publish from rye+bare-token to uv with --check-url (idempotent re-publish) and per-package token env vars; correctly orders slim before heavy and uses --wheel flag.
bin/check-release-environment	Adds dual-token validation, but the slim-token check is systematically bypassed in GHA context because PYPI_TOKEN is always populated from AGENTEX_PYPI_TOKEN by the workflow.
adk/hatch_build.py	Custom hatchling hook that walks ../src/agentex/lib, builds a force_include map, prunes test files, and enforces a minimum-file floor to detect broken walks.
adk/pyproject.toml	New agentex-sdk package manifest; declares agentex-client>=0.12.0 (floor-only by design), 31 ADK deps, requires-python>=3.12, and uses bypass-selection+custom hook for the wheel.
pyproject.toml	Root package renamed to agentex-client with 6 slim deps; adds uv workspace member adk/; excludes src/agentex/lib/** from the wheel to keep slim and heavy disjoint.
.github/workflows/publish-pypi.yml	Passes both AGENTEX_PYPI_TOKEN and AGENTEX_CLIENT_PYPI_TOKEN to the publish script; the PYPI_TOKEN fallback construction is the root cause of the check-release-environment validation gap.
scripts/check-slim-deps	New CI guardrail that parses root pyproject.toml and enforces exactly 6 named slim deps; uses exact-set comparison to catch Stainless inadvertently re-adding ADK deps.
release-please-config.json	Adds two-package mode with include-component-in-tag:true; tag scheme changes from v* to agentex-client-v*/agentex-sdk-v* (flagged as breaking). extra-files correctly moved into the . package entry.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Source["Source Tree (src/agentex/)"]
        slim_src["__init__.py, _*.py\ntypes/, resources/\nprotocol/"]
        lib_src["lib/\n(hand-authored ADK)"]
    end

    subgraph Build["Build"]
        slim_build["hatch wheel\n(root pyproject.toml)\nexclude: src/agentex/lib/**"]
        heavy_build["hatch wheel\n(adk/pyproject.toml)\nhatch_build.py force_include\n../src/agentex/lib/**"]
    end

    subgraph Wheels["Published Wheels"]
        slim_wheel["agentex-client-*.whl\n6 deps, Python >= 3.11"]
        heavy_wheel["agentex-sdk-*.whl\n31 deps, Python >= 3.12\ndepends on agentex-client >= 0.12.0"]
    end

    subgraph Publish["bin/publish-pypi"]
        pub_slim["uv publish slim\ntoken: AGENTEX_CLIENT_PYPI_TOKEN"]
        pub_heavy["uv publish heavy\ntoken: AGENTEX_PYPI_TOKEN"]
    end

    slim_src --> slim_build
    lib_src --> heavy_build
    slim_build --> slim_wheel
    heavy_build --> heavy_wheel
    slim_wheel --> pub_slim
    heavy_wheel --> pub_heavy
    pub_slim --> pub_heavy
    heavy_wheel -.->|"Requires-Dist"| slim_wheel

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 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
bin/check-release-environment:17-18
**Slim-token check is inert in GitHub Actions when `AGENTEX_PYPI_TOKEN` is set**

The workflow unconditionally sets `PYPI_TOKEN: ${{ secrets.AGENTEX_PYPI_TOKEN || secrets.PYPI_TOKEN }}`, so `PYPI_TOKEN` is never empty whenever `AGENTEX_PYPI_TOKEN` is configured. As a result, the condition `[ -z "${AGENTEX_CLIENT_PYPI_TOKEN}" ] && [ -z "${PYPI_TOKEN}" ]` can never fire in a typical GHA run — the script will print "The environment is ready to push releases!" even when `AGENTEX_CLIENT_PYPI_TOKEN` is absent. When the slim publish is then attempted, `uv publish` uses `${AGENTEX_CLIENT_PYPI_TOKEN:-$PYPI_TOKEN}` = the heavy's package-scoped token and hits a 403, rather than the clean "token missing" error the environment check was meant to surface. Consider adding a direct check: `if [ -z "${AGENTEX_CLIENT_PYPI_TOKEN}" ]; then errors+=("..."); fi` so the warning fires regardless of the `PYPI_TOKEN` fallback.

### Issue 2 of 2
examples/tutorials/run_agent_test.sh:140-147
The slim-missing hint says `uv build --wheel`, which only rebuilds the slim. If a developer wiped `dist/` they need both wheels; the correct command is `uv build --all-packages --wheel` — matching the heavy-missing message above it. The same inconsistency exists at the `check_built_wheel` occurrence around line 391.

```suggestion
        if [[ -z "$slim_wheel" ]]; then
            echo -e "${RED}❌ No built slim wheel found in dist/agentex_client-*.whl${NC}"
            echo -e "${YELLOW}💡 Build it first: uv build --all-packages --wheel${NC}"
            cd "$original_dir"
            return 1
        fi

        # Pass both wheels so the local heavy resolves its slim dep locally
```

_{Reviews (14): 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
	pypi/​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.