[maxdubrinsky]

Summary

Generate and package Python gRPC type stubs so editors and type checkers infer concrete request and response types for both synchronous and asynchronous channels. This removes the need for callers to annotate generated RPC callables manually.

Related Issue

Closes #5039

Changes

• Generate gRPC .pyi files with mypy-protobuf, retaining the existing protobuf message generator and runtime bindings.
• Require the new stubs in wheel validation and test response inference, invalid request rejection, and native async transport behavior.
• Update development typing tools and affected annotations, and document generated RPC usage and channel ownership.

Existing synchronous APIs and RPC runtime behavior remain unchanged.

Release Notes

Python gRPC bindings now include concrete request and response types for synchronous and asynchronous calls, improving editor completion and static type checking.

Testing

• Checks appropriate to the affected code and behavior pass.
• Unit tests added/updated.
• E2E tests added/updated (not applicable; no gateway or sandbox runtime changes).

Focused SDK, generation, typing, transport, wheel-verifier, and docs-tool tests pass. Seven typing and transport tests also pass against a clean-source wheel installed outside the checkout. Ruff, full Python type-checking, wheel verification, and legacy --no-pyi generation pass. Documentation validation reports zero errors and three warnings.

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).
• Architecture docs updated (not applicable; Python SDK usage documentation updated).

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5040.docs.buildwithfern.com/openshell

[TaylorMutch]

Reviewed locally at f8a69b3. No blocking findings. The generated declarations provide sync/async request and response inference while preserving existing runtime bindings: all 12 generated runtime files were byte-for-byte identical to generation with the base script.

Validation passed: 185 focused generation, typing, transport, wheel-verifier, and SDK regression tests; repository Python type checks; wheel build and verification; five typing and transport consumer tests against the installed wheel outside the checkout; and independent mypy checks of sync/async response and streaming inference.

The remaining integration considerations are documented: consumers need development dependency stubs, async stub types exist only in .pyi files and require deferred annotations, and low-level channels remain application-owned for TLS, authentication, deadlines, and cleanup. A supported public raw client remains separate work tracked in #2960. Issue #5039 is accepted.