Repository navigation
docs: explain SDK 9 beta installation and cold-start deadlines #1418
Description
The SDK 9 beta setup review in #1412 identified two concrete adopter documentation gaps. Address these during the beta series, before GA.
- Add an adopter-facing beta installation note to README.md. PyPI normalizes the release tag
9.0.0-beta.1to9.0.0b1. Ordinary pip/uv resolution excludes prereleases; showpip install 'adcp==9.0.0b1',pip --pre, and uv's prerelease opt-in. Explain that a stable9.0.0pin is unavailable until GA. Review the package's development-status classifier for the beta channel. - Extend the existing cold-start warm-up documentation to cover per-task, per-version nullable-request-path discovery. Warming the public generated type graph alone does not warm this cache. Document that a very short first-call deadline can expire before dispatch and correctly produce
recovery=None. Evaluate eager cache warming separately; preserve the distinction between a request never dispatched and an uncertain request that needs recovery.
The reviewer measured cold path discovery around 127–204 ms on a loaded machine versus approximately 0.001 ms warm. These are examples, not guaranteed latency bounds. The updated post-dispatch recovery tests explicitly warm this cache and assert dispatch, while existing pre-dispatch timeout coverage remains intact.
Acceptance: an adopter can install the beta from the README and understand the first-call deadline behavior; documentation agrees with the published package version and timeout phase contract.
Activity
bokelley commentedon Oct 6, 2026
Triage
Classification: docs
Bucket(s): docs
Status: ready-to-implement
What the experts said:
"5 - Production/Stable"→"4 - Beta") must change in the same commit that bumps the version to9.0.0b1, not earlier; the measured 127–204 ms latency example will drift with schema growth and should be softened.pip install adcpsilently resolves to 8.x, making the missing beta note a silent failure trap; cold-start extension must also clarify thatrecovery=Nonemeans "never dispatched — safe to retry," not "uncertain dispatch."My take: Experts converge. Both items are documentation-only, non-breaking additions addressing real adopter failure modes. The PR authorization gate is not met (no
/triage executeorauto-pr-ok); this goes to implementation brief.Implementation scope:
pip install adcpfor SDK 9 beta. Showpip install 'adcp==9.0.0b1',pip install --pre adcp, and uv's--prerelease=allow adcp. State "A stable 9.0.0 pin is unavailable until GA." Thepyproject.tomlclassifier change ("5 - Production/Stable"→"4 - Beta") must live in the same commit that bumps the version to9.0.0b1— not in this PR, or the stable 8.x release is mis-classified on PyPI.nullable_request_paths(task_name, version)fromadcp._null_clearis a separate@lru_cachekeyed on(task_name, version)that graph warming does not touch. Cold discovery is "tens to hundreds of milliseconds" (not the 127–204 ms measurement, which will drift with schema size). Add 2–3 sentences near the Per-call task deadlines section distinguishing pre-dispatch timeout (recovery=None— never dispatched, safe to retry) from post-dispatch timeout (recoveryset — seller may have committed); cross-link the two sections.ruff check .,black --check .(docs-only — no pytest needed). Suggested branch:claude/issue-1418-sdk9-beta-install-docs.Triaged by Claude Code. Session: https://claude.ai/code/session_01PxtbanfeDsVkTpyZtCEmU5
Generated by Claude Code