feat: add declarative reconnect flag with transport-factory auto-disable (#720)
## Summary
Adds a new `reconnect: bool = True` kwarg to `DeepgramClient` and
`AsyncDeepgramClient`. When a custom `transport_factory` is provided,
`reconnect` is auto-set to `False` to signal that the custom transport
owns its own retry/reconnect lifecycle.
## Why
Custom transports (e.g., the SageMaker transport in
`deepgram-python-sdk-transport-sagemaker`) implement their own retry and
reconnect logic — full-jitter backoff, retry-budget windows, replay
buffers, etc. Stacking SDK-level retries on top of that would cause
storm-on-storm behavior under burst load, which is the failure mode that
motivated this parity work across the SDKs.
This adds an explicit, declarative way to express "the SDK is not
responsible for reconnects." Today the Python SDK has no wrapper
reconnect layer (the `websockets` library doesn't auto-reconnect;
transports manage their own), so the flag is **declarative only**: it
documents intent and reserves the slot for any future SDK-side reconnect
logic.
## Parity with other SDKs
- Mirrors the `reconnect` parity work in `deepgram-java-sdk`
- Same flag added to `deepgram-js-sdk` in PR #492
(`gh/pluggable-transport-sagemaker`)
## Behavior
```python
# Default — reconnect=True, no custom transport: SDK behaves as before
client = DeepgramClient(api_key="...")
assert client.reconnect is True
# Custom transport — reconnect auto-disabled to False
client = DeepgramClient(api_key="...", transport_factory=my_factory)
assert client.reconnect is False
# Explicit opt-in even with custom transport — caller takes responsibility
client = DeepgramClient(
api_key="...",
transport_factory=my_factory,
reconnect=True,
)
assert client.reconnect is True
```
## Test plan
Covered in `tests/custom/test_transport.py`:
- [x] Default state: `client.reconnect == True`
- [x] Explicit `reconnect=False` is respected
- [x] `transport_factory` auto-disables → `reconnect == False`
- [x] Explicit override `transport_factory=..., reconnect=True` is
respected
## Release impact
- `feat:` → minor version bump per release-please conventions
- Fully backwards-compatible — new optional kwarg with sensible default;
existing callers need no change
- No regen impact: hand-written patch to `src/deepgram/client.py`,
already in `.fernignore` G
Greg Holmes committed
b5d590577429adeacfe2068df4c33201a158c9de
Parent: ffdb746
Committed by GitHub <noreply@github.com>
on 6/1/2026, 1:20:04 PM