feat!: implements new generated SDK architecture, all call signatures #572
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Contributor
WalkthroughThis PR removes a large portion of the legacy SDK surface (clients, routers, common abstractions, audio I/O, models, and many CI/dev docs/configs) and adds new GitHub Actions workflows and Release Please configuration. It also updates repository metadata (README, CONTRIBUTING, LICENSE). Changes
Sequence Diagram(s)Estimated code review effort🎯 5 (Critical) | ⏱️ ~120+ minutes Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This change switches us from hand-rolled to generated spec-based API specs. BREAKING CHANGE: This is a significant breaking change, and should be carried out in conjunction with our migration guide.
- Remove unused json5 dependency - Keep python-dotenv>=1.0.0 requirement
- Add type ignore comments to suppress mypy warnings for Pydantic v2 model_config - Improves type checking compatibility across Pydantic versions
- Update all agent v1 socket event and message type definitions - Improve type safety and consistency across agent socket communications - Include updates for audio, conversation, function call, injection, prompt, settings, and warning events
- Remove old integration test directory and README - Add new comprehensive unit test suite with proper organization - Rename tests/integration to tests/integrations for consistency - Add extensive unit tests for core functionality, models, and telemetry - Improve test coverage and maintainability
- Refresh websockets API reference with latest changes - Update examples and type definitions - Improve documentation clarity and completeness
- Add explicit type annotations for Pydantic constrained types in agent_v1_settings_message.py - Fix WebSocket protocol type assignments in instrumented_socket.py - Remove non-existent AgentV1Speak import from sockets/__init__.py - Add runtime type checking for dictionary access in batching_handler.py - Fix telemetry handler method signatures in telemetry_events.py - Add missing return type annotations to client constructors Resolves 22 mypy errors across 5 files while maintaining full backward compatibility. All 829 tests continue to pass.
Ensure tests only run after successful type checking to fail fast on type errors.
Focus type checking on source code rather than entire repository for better performance and cleaner output.
- Replace dict[...] with Dict[...] for Python 3.8 compatibility - Replace list[...] with List[...] for Python 3.8 compatibility - Add necessary imports from typing module - Maintain mypy compliance while supporting older Python versions This ensures the CI workflow using Python 3.8 will pass type checking.
- Fix typing.Annotated import with fallback to typing_extensions - Replace all X | Y union syntax with Union[X, Y] for Python 3.8 - Add proper type ignore comments for assignment and valid-type errors - Fix cast targets in instrumented_http.py to use Union syntax All 524 source files now pass mypy type checking on Python 3.8. This resolves the CI compile job failures.
Add type: ignore[valid-type] comments to all usages of custom type aliases: - Temperature0to2 usage in OpenAI, AWS Bedrock, Google, and Groq providers - Temperature0to1 usage in Anthropic provider - IntContextLength usage in Think configuration This resolves the remaining 6 mypy valid-type errors while maintaining proper type checking for Pydantic constrained types.
…bility - Replace X | Y union syntax with Union[X, Y] in test_telemetry_handler.py - Add Union import to support Python 3.8 type annotations - Fix runtime TypeError that was preventing test collection This resolves the CI test job failure on Python 3.8 where union syntax caused 'unsupported operand type(s) for |' runtime error.
- Add GetModelV1ResponseMetadata import to test_manage_client.py - Replace isinstance(result, GetModelV1Response) with isinstance(result, (GetModelV1ResponseBatch, GetModelV1ResponseMetadata)) - Fix Python 3.8 TypeError: 'Subscripted generics cannot be used with class and instance checks' This resolves the 2 failing integration tests that were using isinstance() with typing.Union types, which is not supported in Python 3.8.
- Add release-please config for multi-channel releases (alpha/beta/rc/stable) - Configure changelog generation with conventional commit sections - Set up manifest file tracking current version (5.0.0) - Fix version.py to read from correct package name 'deepgram' - Update CI workflow with Python 3.8-3.13 matrix for comprehensive testing This enables automated release management with changelog generation based on conventional commits across multiple release channels.
- Add detailed migration guide covering all API changes from v3+ to v5.0.0 - Include configuration and authentication changes - Provide before/after examples for all API methods in order: - Auth V1, Listen V1, Speak V1, Agent V1, Read V1, Models V1, Manage V1, Self-Hosted V1 - Integrate WebSocket examples inline with corresponding REST endpoints - Document response type differences (synchronous vs asynchronous with callbacks) - Use consistent UUID4 format for all example IDs - Add migration checklist and breaking changes summary
- Remove custom markdown components (<Info>, <CodeGroup>, etc.) - Adopt same structure and format as v3-to-v5 migration guide - Organize API methods by family (Listen V1, Manage V1) - Use consistent UUID4 format for all example IDs - Integrate WebSocket examples inline with REST endpoints - Add comprehensive breaking changes summary and migration checklist - Convert all examples to standard markdown code blocks with clear before/after labels
- Add comprehensive v5.0.0 usage examples and API documentation - Include links to both migration guides (v2-to-v3 and v3-to-v5) - Update authentication methods and environment variable documentation - Add WebSocket examples for Listen V1/V2, Speak V1, and Agent V1 - Include advanced features like raw response access and custom HTTP clients
Upstream generator changes removed MediaTranscribeRequestLanguage and TextAnalyzeRequestLanguage enum types, replacing them with plain string parameters. Removed unused imports from test files to resolve ImportError.
lukeocodes changed the title lukeocodes changed the title There was a problem hiding this comment.
Pull Request Overview
This PR implements a new generated SDK architecture based on API specifications, replacing the existing hand-rolled implementation. It includes breaking changes to all call signatures and requires users to follow a migration guide for upgrading to the new architecture.
- Removes the existing manual SDK implementation files across multiple client types (manage, live, listen, auth, analyze)
- Transitions from hand-written to auto-generated code using Fern for SDK generation
- Maintains backward compatibility support while introducing new architecture
Reviewed Changes
Copilot reviewed 120 out of 1002 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| deepgram/clients/manage/ | Complete removal of hand-rolled management client implementation including options, client logic, and response handling |
| deepgram/clients/live/ | Removal of live transcription client wrapper and routing logic |
| deepgram/clients/listen/ | Elimination of REST and WebSocket listen clients, options, and response structures |
| deepgram/clients/auth/ | Removal of authentication client implementation and response types |
| deepgram/clients/analyze/ | Deletion of analyze client functionality and supporting code |
| deepgram/clients/common/ | Removal of shared abstractions, response types, and utility functions |
| deepgram/clients/errors.py | Deletion of module-specific error handling |
| deepgram/clients/listen_router.py | Removal of routing logic for listen client versions |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 8
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (13)
.github/images/git_workflow.pngis excluded by!**/*.pngexamples/fixtures/audio.mp3is excluded by!**/*.mp3examples/fixtures/audio.wavis excluded by!**/*.wavexamples/speech-to-text/rest/async/file/preamble.wavis excluded by!**/*.wavexamples/speech-to-text/rest/callback/callback/preamble.wavis excluded by!**/*.wavexamples/speech-to-text/rest/intent/CallCenterPhoneCall.mp3is excluded by!**/*.mp3examples/speech-to-text/rest/sentiment/CallCenterPhoneCall.mp3is excluded by!**/*.mp3examples/speech-to-text/rest/stream_file/preamble.wavis excluded by!**/*.wavexamples/speech-to-text/rest/summary/CallCenterPhoneCall.mp3is excluded by!**/*.mp3examples/speech-to-text/rest/sync/file/preamble.wavis excluded by!**/*.wavexamples/speech-to-text/rest/topic/CallCenterPhoneCall.mp3is excluded by!**/*.mp3examples/speech-to-text/websocket/replay/microsoft_headquarters.wavis excluded by!**/*.wavpoetry.lockis excluded by!**/*.lock
📒 Files selected for processing (107)
.devcontainer/Dockerfile(0 hunks).devcontainer/devcontainer.json(0 hunks).env.example(0 hunks).fernignore(1 hunks).github/.release-please-manifest.json(1 hunks).github/BRANCH_AND_RELEASE_PROCESS.md(0 hunks).github/CODE_CONTRIBUTIONS_GUIDE.md(0 hunks).github/CODE_OF_CONDUCT.md(0 hunks).github/CONTRIBUTING.md(0 hunks).github/GITHUB_WORKFLOW.md(0 hunks).github/ISSUE_TEMPLATE/bug_report.md(0 hunks).github/ISSUE_TEMPLATE/bug_report.yml(1 hunks).github/ISSUE_TEMPLATE/config.yml(0 hunks).github/ISSUE_TEMPLATE/docs_improvement.yml(1 hunks).github/ISSUE_TEMPLATE/feature_request.md(0 hunks).github/ISSUE_TEMPLATE/feature_request.yml(1 hunks).github/PULL_REQUEST_TEMPLATE.md(0 hunks).github/release-please-config.json(1 hunks).github/workflows/CD-dev.yml(0 hunks).github/workflows/CD.yaml(0 hunks).github/workflows/CI.yaml(0 hunks).github/workflows/PyDocs.yaml(0 hunks).github/workflows/check-actionlint.yaml(0 hunks).github/workflows/check-all.yaml(0 hunks).github/workflows/check-lint.yaml(0 hunks).github/workflows/check-mdlint.yaml(0 hunks).github/workflows/check-shell.yaml(0 hunks).github/workflows/check-static.yaml(0 hunks).github/workflows/check-yaml.yaml(0 hunks).github/workflows/ci.yml(1 hunks).github/workflows/publish.yml(1 hunks).github/workflows/release-please.yml(1 hunks).github/workflows/tests-daily.yaml(0 hunks).github/workflows/tests-daily.yml(1 hunks).github/workflows/tests-unit.yaml(0 hunks).gitignore(1 hunks).markdownlintrc(0 hunks).pylintrc(0 hunks).yamllintconfig.yaml(0 hunks)CODE_OF_CONDUCT.md(0 hunks)CONTRIBUTING.md(1 hunks)LICENSE(2 hunks)Makefile(0 hunks)README.md(1 hunks)deepgram/__init__.py(0 hunks)deepgram/audio/__init__.py(0 hunks)deepgram/audio/microphone/__init__.py(0 hunks)deepgram/audio/microphone/constants.py(0 hunks)deepgram/audio/microphone/errors.py(0 hunks)deepgram/audio/microphone/microphone.py(0 hunks)deepgram/audio/speaker/__init__.py(0 hunks)deepgram/audio/speaker/constants.py(0 hunks)deepgram/audio/speaker/errors.py(0 hunks)deepgram/audio/speaker/speaker.py(0 hunks)deepgram/client.py(0 hunks)deepgram/clients/__init__.py(0 hunks)deepgram/clients/agent/__init__.py(0 hunks)deepgram/clients/agent/client.py(0 hunks)deepgram/clients/agent/enums.py(0 hunks)deepgram/clients/agent/v1/__init__.py(0 hunks)deepgram/clients/agent/v1/websocket/__init__.py(0 hunks)deepgram/clients/agent/v1/websocket/async_client.py(0 hunks)deepgram/clients/agent/v1/websocket/client.py(0 hunks)deepgram/clients/agent/v1/websocket/options.py(0 hunks)deepgram/clients/agent/v1/websocket/response.py(0 hunks)deepgram/clients/agent_router.py(0 hunks)deepgram/clients/analyze/__init__.py(0 hunks)deepgram/clients/analyze/client.py(0 hunks)deepgram/clients/analyze/v1/__init__.py(0 hunks)deepgram/clients/analyze/v1/async_client.py(0 hunks)deepgram/clients/analyze/v1/client.py(0 hunks)deepgram/clients/analyze/v1/helpers.py(0 hunks)deepgram/clients/analyze/v1/options.py(0 hunks)deepgram/clients/analyze/v1/response.py(0 hunks)deepgram/clients/auth/__init__.py(0 hunks)deepgram/clients/auth/client.py(0 hunks)deepgram/clients/auth/v1/__init__.py(0 hunks)deepgram/clients/auth/v1/async_client.py(0 hunks)deepgram/clients/auth/v1/client.py(0 hunks)deepgram/clients/auth/v1/response.py(0 hunks)deepgram/clients/common/__init__.py(0 hunks)deepgram/clients/common/v1/__init__.py(0 hunks)deepgram/clients/common/v1/abstract_async_rest.py(0 hunks)deepgram/clients/common/v1/abstract_async_websocket.py(0 hunks)deepgram/clients/common/v1/abstract_sync_rest.py(0 hunks)deepgram/clients/common/v1/abstract_sync_websocket.py(0 hunks)deepgram/clients/common/v1/enums.py(0 hunks)deepgram/clients/common/v1/errors.py(0 hunks)deepgram/clients/common/v1/helpers.py(0 hunks)deepgram/clients/common/v1/options.py(0 hunks)deepgram/clients/common/v1/rest_response.py(0 hunks)deepgram/clients/common/v1/shared_response.py(0 hunks)deepgram/clients/common/v1/websocket_events.py(0 hunks)deepgram/clients/common/v1/websocket_response.py(0 hunks)deepgram/clients/errors.py(0 hunks)deepgram/clients/listen/__init__.py(0 hunks)deepgram/clients/listen/client.py(0 hunks)deepgram/clients/listen/enums.py(0 hunks)deepgram/clients/listen/v1/__init__.py(0 hunks)deepgram/clients/listen/v1/rest/__init__.py(0 hunks)deepgram/clients/listen/v1/rest/async_client.py(0 hunks)deepgram/clients/listen/v1/rest/client.py(0 hunks)deepgram/clients/listen/v1/rest/helpers.py(0 hunks)deepgram/clients/listen/v1/rest/options.py(0 hunks)deepgram/clients/listen/v1/rest/response.py(0 hunks)deepgram/clients/listen/v1/websocket/__init__.py(0 hunks)deepgram/clients/listen/v1/websocket/async_client.py(0 hunks)
⛔ Files not processed due to max files limit (14)
- deepgram/clients/listen/v1/websocket/client.py
- deepgram/clients/listen/v1/websocket/options.py
- deepgram/clients/listen/v1/websocket/response.py
- deepgram/clients/listen_router.py
- deepgram/clients/live/init.py
- deepgram/clients/live/v1/init.py
- deepgram/clients/live/v1/client.py
- deepgram/clients/live/v1/enums.py
- deepgram/clients/manage/init.py
- deepgram/clients/manage/client.py
- deepgram/clients/manage/v1/init.py
- deepgram/clients/manage/v1/async_client.py
- deepgram/clients/manage/v1/client.py
- deepgram/clients/manage/v1/options.py
💤 Files with no reviewable changes (93)
- .github/CODE_OF_CONDUCT.md
- .github/workflows/tests-unit.yaml
- .github/ISSUE_TEMPLATE/config.yml
- .github/CONTRIBUTING.md
- CODE_OF_CONDUCT.md
- deepgram/clients/errors.py
- .github/GITHUB_WORKFLOW.md
- .github/workflows/check-lint.yaml
- deepgram/clients/auth/v1/init.py
- deepgram/audio/microphone/errors.py
- deepgram/audio/speaker/errors.py
- deepgram/clients/auth/v1/async_client.py
- deepgram/clients/analyze/v1/client.py
- .github/ISSUE_TEMPLATE/feature_request.md
- .github/BRANCH_AND_RELEASE_PROCESS.md
- deepgram/clients/agent_router.py
- .github/workflows/CI.yaml
- deepgram/clients/agent/enums.py
- .github/workflows/check-actionlint.yaml
- deepgram/clients/agent/v1/websocket/client.py
- deepgram/clients/agent/v1/websocket/init.py
- .github/workflows/check-static.yaml
- .github/workflows/check-yaml.yaml
- .markdownlintrc
- .github/workflows/CD-dev.yml
- deepgram/clients/common/v1/websocket_response.py
- .github/PULL_REQUEST_TEMPLATE.md
- .devcontainer/devcontainer.json
- deepgram/clients/listen/client.py
- deepgram/clients/listen/v1/websocket/init.py
- .github/workflows/check-mdlint.yaml
- deepgram/clients/common/v1/rest_response.py
- deepgram/audio/microphone/microphone.py
- deepgram/clients/common/v1/abstract_async_websocket.py
- deepgram/clients/common/v1/errors.py
- deepgram/clients/analyze/v1/helpers.py
- deepgram/clients/auth/init.py
- .env.example
- deepgram/clients/common/v1/websocket_events.py
- deepgram/clients/analyze/client.py
- deepgram/clients/common/v1/abstract_sync_websocket.py
- deepgram/clients/auth/v1/client.py
- deepgram/audio/init.py
- deepgram/init.py
- deepgram/clients/listen/v1/rest/options.py
- deepgram/clients/listen/enums.py
- deepgram/clients/common/v1/abstract_sync_rest.py
- deepgram/clients/common/v1/options.py
- .github/workflows/CD.yaml
- deepgram/clients/listen/v1/websocket/async_client.py
- deepgram/clients/auth/v1/response.py
- deepgram/clients/listen/v1/rest/client.py
- Makefile
- deepgram/audio/microphone/init.py
- .github/CODE_CONTRIBUTIONS_GUIDE.md
- deepgram/clients/common/v1/enums.py
- deepgram/clients/agent/v1/init.py
- deepgram/audio/microphone/constants.py
- .devcontainer/Dockerfile
- deepgram/clients/agent/client.py
- deepgram/clients/agent/v1/websocket/response.py
- .github/workflows/check-all.yaml
- deepgram/audio/speaker/constants.py
- deepgram/clients/analyze/v1/response.py
- deepgram/clients/listen/v1/init.py
- deepgram/clients/common/init.py
- deepgram/clients/agent/v1/websocket/async_client.py
- deepgram/clients/agent/init.py
- deepgram/clients/analyze/v1/async_client.py
- .yamllintconfig.yaml
- deepgram/clients/listen/v1/rest/init.py
- deepgram/clients/agent/v1/websocket/options.py
- deepgram/client.py
- deepgram/clients/analyze/v1/options.py
- deepgram/clients/analyze/init.py
- .github/workflows/check-shell.yaml
- deepgram/clients/analyze/v1/init.py
- .github/workflows/PyDocs.yaml
- .github/ISSUE_TEMPLATE/bug_report.md
- deepgram/clients/listen/v1/rest/helpers.py
- deepgram/clients/common/v1/abstract_async_rest.py
- .pylintrc
- deepgram/audio/speaker/init.py
- deepgram/clients/common/v1/helpers.py
- deepgram/clients/common/v1/init.py
- deepgram/audio/speaker/speaker.py
- deepgram/clients/init.py
- .github/workflows/tests-daily.yaml
- deepgram/clients/listen/v1/rest/response.py
- deepgram/clients/auth/client.py
- deepgram/clients/listen/v1/rest/async_client.py
- deepgram/clients/common/v1/shared_response.py
- deepgram/clients/listen/init.py
🧰 Additional context used
🪛 actionlint (1.7.7)
.github/workflows/release-please.yml
23-23: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
43-43: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
.github/workflows/tests-daily.yml
18-18: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
38-38: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
.github/workflows/publish.yml
20-20: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
40-40: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
63-63: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
.github/workflows/ci.yml
15-15: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
35-35: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
🔇 Additional comments (7)
LICENSE (1)
3-3: License year bump looks good.Updating the copyright notice to 2025 with proper capitalization keeps the MIT license accurate for this release.
.gitignore (1)
2-14: Expanded ignore list LGTM.These additions cover common Python/Poetry artifacts and help keep the repo clean. Nicely scoped.
.fernignore (5)
1-10: LGTM!The development, configuration, and documentation files are appropriately excluded from Fern code generation.
12-13: LGTM!Examples should remain hand-written to demonstrate SDK usage patterns and are correctly excluded from generation.
15-17: LGTM!Test files should remain hand-written and are correctly excluded from generation.
19-21: LGTM!The custom extensions and client wrapper are appropriately protected from code generation, allowing for custom SDK functionality beyond the generated code.
23-27: Socket clients excluded from generation - maintenance consideration.The socket client implementations are appropriately excluded from generation since WebSocket clients require custom stateful connection management, event handling, and reconnection logic that cannot be easily generated from API specs. However, maintaining these manually across multiple API versions (v1, v2) could become a maintenance burden.
Consider documenting the rationale for hand-rolling these socket clients and whether any patterns can be abstracted to reduce duplication across versions.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
.github/workflows/ci.yml(1 hunks).github/workflows/publish.yml(1 hunks).github/workflows/release-please.yml(1 hunks).github/workflows/tests-daily.yml(1 hunks)CONTRIBUTING.md(1 hunks)README.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- .github/workflows/ci.yml
🚧 Files skipped from review as they are similar to previous changes (3)
- .github/workflows/publish.yml
- .github/workflows/release-please.yml
- .github/workflows/tests-daily.yml
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
Proposed changes
This change switches us from hand-rolled to generated architecture based on our API specs. For SDK changes for generated files, please make the appropriate change to our specs
BREAKING CHANGE: This change impacts all call signatures, a migration a guide is available
Types of changes
What types of changes does your code introduce to the community Python SDK?
Put an
xin the boxes that applyChecklist
Put an
xin the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.Further comments
This is our move from hand-rolled to auto-generated SDK architecture using Fern
Summary by CodeRabbit