feat!: v6 — fully generated SDK with latest APIs and WebSocket support (#640)

## Summary

This is the Deepgram Python SDK v6 release. The SDK moves to a fully
Fern-generated architecture, replacing all hand-rolled WebSocket code
from v5 with generated, type-safe implementations aligned with the
latest API spec.

### What's changing

- **Fully generated WebSocket clients** — Listen v1/v2, Speak v1, and
Agent v1 WebSocket implementations are now generated from the API spec,
replacing the manually maintained code in v5. This means faster feature
delivery and fewer SDK-specific bugs.
- **Latest APIs and features** — Includes all current Deepgram API
capabilities: Listen v2 (conversational speech recognition with turn
detection), Agent v1 (voice agents), and the latest Speak v1 features.
- **Simplified send methods** — `send_media()` now accepts raw `bytes`
directly. Control messages use dedicated methods (`send_keep_alive()`,
`send_finalize()`, `send_flush()`, etc.) instead of the generic
`send_control()` pattern.
- **New type system** — Types are generated per-domain
(`deepgram.listen.v1.types`, `deepgram.agent.v1.types`,
`deepgram.types`) instead of the shared
`deepgram.extensions.types.sockets` barrel import.
- **22 production-ready examples** covering authentication,
transcription (file, URL, live), voice agents, TTS, text intelligence,
and management APIs.
- **CI/CD improvements** — Matrix testing across Python 3.8–3.13,
release-please workflow, PR title validation.

### Breaking changes

- All imports from `deepgram.extensions.types.sockets` must be updated
to domain-specific type packages
- `send_control()` replaced by dedicated methods per WebSocket client
- `send_media()` now takes `bytes` instead of wrapper message types
- Agent settings types renamed to match generated schema hierarchy (e.g.
`AgentV1SettingsMessage` → `AgentV1Settings`)

### Documentation

- **[Migration guide](docs/Migrating-v5-to-v6.md)** — Complete v5 to v6
migration guide
- **[API Reference](reference.md)** — Full REST and WebSocket reference
with v6 types and examples

---------

Co-authored-by: fern-api[bot] <115122769+fern-api[bot]@users.noreply.github.com>

Author: lukeocodes

.fern/metadata.json

@@ -0,0 +1,17 @@
+{
+  "cliVersion": "3.77.1",
+  "generatorName": "fernapi/fern-python-sdk",
+  "generatorVersion": "4.57.2",
+  "generatorConfig": {
+    "client": {
+      "class_name": "BaseClient",
+      "filename": "base_client.py",
+      "exported_class_name": "DeepgramClient",
+      "exported_filename": "client.py"
+    },
+    "use_typeddict_requests": true,
+    "should_generate_websocket_clients": true,
+    "enable_wire_tests": true
+  },
+  "sdkVersion": "6.0.0-beta.4"
+}

.fernignore

@@ -1,33 +1,39 @@
-# Development, Configuration Files & Documentation
-README.md
-CONTRIBUTING.md
-.vscode/
-.gitignore
-mypy.ini
-websockets-reference.md
-.github/
-scripts/run_examples.sh
-docs/
-pyproject.toml
-CHANGELOG.md
+# Custom client implementation extending BaseClient with additional features:
+# - access_token parameter support (Bearer token authentication)
+# - Automatic session ID generation and header injection (x-deepgram-session-id)
+# This file is manually maintained and should not be regenerated
+src/deepgram/client.py
 
-# Examples
-examples/
+# WireMock mappings: removed duplicate empty-body /v1/listen stub that causes
+# non-deterministic matching failures
+wiremock/wiremock-mappings.json
 
-# Test Files
-tests/unit/
-tests/integrations/
+# Wire test with manual fix: transcribe_file() requires request=bytes parameter
+tests/wire/test_listen_v1_media.py
 
-# Custom Extensions & Clients
-src/deepgram/client.py
-src/deepgram/extensions/
-
-# Socket Client Implementations
-src/deepgram/agent/v1/socket_client.py
+# WebSocket socket clients: optional message parameter defaults for send_flush,
+# send_close, send_clear, send_finalize, send_close_stream, send_keep_alive
+src/deepgram/speak/v1/socket_client.py
 src/deepgram/listen/v1/socket_client.py
 src/deepgram/listen/v2/socket_client.py
-src/deepgram/speak/v1/socket_client.py
+src/deepgram/agent/v1/socket_client.py
+
+# Manual standalone tests
+tests/manual
+
+# README with custom examples, migration guide links, and contributing section
+README.md
+
+# Changelog managed by release-please
+CHANGELOG.md
+
+# Contributing guide
+CONTRIBUTING.md
+
+# Reference with Fern-generated REST API docs plus manually maintained WebSocket sections
+reference.md
 
-# Bug Fixes
-src/deepgram/listen/client.py
-src/deepgram/core/client_wrapper.py
+# Folders to ignore
+.github
+docs
+examples

.github/.commitlintrc.json

@@ -49,4 +49,5 @@
             100
         ]
     }
-}
+}
+

.github/workflows/changelog-log.yml

@@ -36,3 +36,4 @@ jobs:
                   #   include_body_raw: "false"
                   #   log_level: "warn" # trace, debug, info, warn, error, fatal
                   #   extra_body_json: '{"custom":"field"}'  # merge custom fields into payload
+

.github/workflows/ci.yml

@@ -18,6 +18,9 @@ jobs:
       - name: Bootstrap poetry
         run: |
           curl -sSL https://install.python-poetry.org | python - -y --version 1.5.1
+      - name: Add poetry to PATH
+        run: |
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
       - name: Install dependencies
         run: poetry install
       - name: Compile
@@ -38,8 +41,42 @@ jobs:
       - name: Bootstrap poetry
         run: |
           curl -sSL https://install.python-poetry.org | python - -y --version 1.5.1
+      - name: Add poetry to PATH
+        run: |
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
       - name: Install dependencies
         run: poetry install
 
+      - name: Verify Docker is available
+        run: |
+          docker --version
+          docker compose version
+
       - name: Test
         run: poetry run pytest -rP .
+
+  publish:
+    needs: [compile, test]
+    if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.8"
+      - name: Bootstrap poetry
+        run: |
+          curl -sSL https://install.python-poetry.org | python - -y --version 1.5.1
+      - name: Add poetry to PATH
+        run: |
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      - name: Install dependencies
+        run: poetry install
+      - name: Build package
+        run: poetry build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/pr-title-check.yml

@@ -30,3 +30,4 @@ jobs:
                   PR_TITLE: ${{ github.event.pull_request.title }}
               run: |
                   echo "$PR_TITLE" | npx commitlint -g .github/.commitlintrc.json
+

.github/workflows/tests-daily.yml

@@ -44,5 +44,10 @@ jobs:
       - name: Install dependencies
         run: poetry install
 
+      - name: Verify Docker is available
+        run: |
+          docker --version
+          docker compose version
+
       - name: Test
         run: poetry run pytest -rP .

.gitignore

@@ -3,17 +3,3 @@
 __pycache__/
 dist/
 poetry.toml
-.env
-.pytest_cache/
-
-# ignore example output files
-examples/**/output.*
-
-# ignore venv
-venv/
-.DS_Store
-
-# ignore build artifacts and dependencies
-Pipfile
-Pipfile.lock
-deepgram_sdk.egg-info/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Deepgram.
+Copyright (c) 2026 Deepgram.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -13,8 +13,9 @@ Comprehensive API documentation and guides are available at [developers.deepgram
 
 ### Migrating From Earlier Versions
 
+- [v5 to v6](./docs/Migrating-v5-to-v6.md) (current)
+- [v3+ to v5](./docs/Migrating-v3-to-v5.md)
 - [v2 to v3+](./docs/Migrating-v2-to-v3.md)
-- [v3+ to v5](./docs/Migrating-v3-to-v5.md) (current)
 
 ## Installation
 
@@ -26,8 +27,7 @@ pip install deepgram-sdk
 
 ## Reference
 
-- **[API Reference](./reference.md)** - Complete reference for all SDK methods and parameters
-- **[WebSocket Reference](./websockets-reference.md)** - Detailed documentation for real-time WebSocket connections
+- **[API Reference](./reference.md)** - Complete reference for all SDK methods, parameters, and WebSocket connections
 
 ## Usage
 
@@ -37,7 +37,7 @@ The Deepgram SDK provides both synchronous and asynchronous clients for all majo
 
 #### Real-time Speech Recognition (Listen v2)
 
-Our newest and most advanced speech recognition model with contextual turn detection ([WebSocket Reference](./websockets-reference.md#listen-v2-connect)):
+Our newest and most advanced speech recognition model with contextual turn detection ([Reference](./reference.md#listen-v2-connect)):
 
 ```python
 from deepgram import DeepgramClient
@@ -48,7 +48,7 @@ client = DeepgramClient()
 with client.listen.v2.connect(
     model="flux-general-en",
     encoding="linear16",
-    sample_rate="16000"
+    sample_rate=16000
 ) as connection:
     def on_message(message):
         print(f"Received {message.type} event")
@@ -118,39 +118,45 @@ response = client.read.v1.text.analyze(
 
 #### Voice Agent (Conversational AI)
 
-Build interactive voice agents ([WebSocket Reference](./websockets-reference.md#agent-v1-connect)):
+Build interactive voice agents ([Reference](./reference.md#agent-v1-connect)):
 
 ```python
 from deepgram import DeepgramClient
-from deepgram.extensions.types.sockets import (
-    AgentV1SettingsMessage, AgentV1Agent, AgentV1AudioConfig,
-    AgentV1AudioInput, AgentV1Listen, AgentV1ListenProvider,
-    AgentV1Think, AgentV1OpenAiThinkProvider, AgentV1SpeakProviderConfig,
-    AgentV1DeepgramSpeakProvider
+from deepgram.agent.v1.types import (
+    AgentV1Settings, AgentV1SettingsAgent,
+    AgentV1SettingsAgentListen, AgentV1SettingsAgentListenProvider_V1,
+    AgentV1SettingsAudio, AgentV1SettingsAudioInput,
 )
+from deepgram.types.think_settings_v1 import ThinkSettingsV1
+from deepgram.types.think_settings_v1provider import ThinkSettingsV1Provider_OpenAi
+from deepgram.types.speak_settings_v1 import SpeakSettingsV1
+from deepgram.types.speak_settings_v1provider import SpeakSettingsV1Provider_Deepgram
 
 client = DeepgramClient()
 
 with client.agent.v1.connect() as agent:
-    settings = AgentV1SettingsMessage(
-        audio=AgentV1AudioConfig(
-            input=AgentV1AudioInput(encoding="linear16", sample_rate=44100)
+    settings = AgentV1Settings(
+        audio=AgentV1SettingsAudio(
+            input=AgentV1SettingsAudioInput(encoding="linear16", sample_rate=24000)
         ),
-        agent=AgentV1Agent(
-            listen=AgentV1Listen(
-                provider=AgentV1ListenProvider(type="deepgram", model="nova-3")
+        agent=AgentV1SettingsAgent(
+            listen=AgentV1SettingsAgentListen(
+                provider=AgentV1SettingsAgentListenProvider_V1(
+                    type="deepgram", model="nova-3"
+                )
             ),
-            think=AgentV1Think(
-                provider=AgentV1OpenAiThinkProvider(
+            think=ThinkSettingsV1(
+                provider=ThinkSettingsV1Provider_OpenAi(
                     type="open_ai", model="gpt-4o-mini"
-                )
+                ),
+                prompt="You are a helpful AI assistant.",
             ),
-            speak=AgentV1SpeakProviderConfig(
-                provider=AgentV1DeepgramSpeakProvider(
+            speak=SpeakSettingsV1(
+                provider=SpeakSettingsV1Provider_Deepgram(
                     type="deepgram", model="aura-2-asteria-en"
                 )
-            )
-        )
+            ),
+        ),
     )
 
     agent.send_settings(settings)
@@ -161,18 +167,14 @@ with client.agent.v1.connect() as agent:
 
 For comprehensive documentation of all available methods, parameters, and options:
 
-- **[API Reference](./reference.md)** - Complete reference for REST API methods including:
+- **[API Reference](./reference.md)** - Complete reference for all SDK methods including:
 
   - Listen (Speech-to-Text): File transcription, URL transcription, and media processing
   - Speak (Text-to-Speech): Audio generation and voice synthesis
   - Read (Text Intelligence): Text analysis, sentiment, summarization, and topic detection
   - Manage: Project management, API keys, and usage analytics
   - Auth: Token generation and authentication management
-
-- **[WebSocket Reference](./websockets-reference.md)** - Detailed documentation for real-time connections:
-  - Listen v1/v2: Real-time speech recognition with different model capabilities
-  - Speak v1: Real-time text-to-speech streaming
-  - Agent v1: Conversational voice agents with integrated STT, LLM, and TTS
+  - WebSocket connections: Listen v1/v2, Speak v1, and Agent v1 real-time streaming
 
 ## Authentication
 
@@ -242,7 +244,7 @@ async def main():
     async with client.listen.v2.connect(
         model="flux-general-en",
         encoding="linear16",
-        sample_rate="16000"
+        sample_rate=16000
     ) as connection:
         async def on_message(message):
             print(f"Received {message.type} event")
@@ -378,7 +380,7 @@ We welcome contributions to improve this SDK! However, please note that this lib
 
 5. **Run examples**:
    ```bash
-   python -u examples/listen/v2/connect/main.py
+   python -u examples/07-transcription-live-websocket.py
    ```
 
 ### Contribution Guidelines