docs: add auto-generated code documentation by enesgules · Pull Request #698 · deepgram/deepgram-python-sdk

enesgules · 2026-04-27T14:10:54Z

Auto-generated Code Documentation

AI-analyzed source code to produce structured documentation including:

Architecture overview with diagrams
Core concepts and internals
API reference with parameter tables
Practical usage guides

Copilot

Pull request overview

Adds a new set of auto-generated documentation pages (architecture, concepts, guides, and API reference) for the Deepgram Python SDK.

Changes:

Introduces a “Getting Started” landing page plus architecture and client lifecycle concept docs.
Adds task-focused guides for authentication, live transcription, TTS workflows, and management automation.
Adds API reference pages for major domains (Listen/Speak/Read/Manage/Auth/Agent) and helpers/types.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
docs/codedocs/index.md	New “Getting Started” entry page for the codedocs set.
docs/codedocs/architecture.md	Architecture overview and diagrams for generated + handwritten layers.
docs/codedocs/client-lifecycle.md	Concept page describing client construction, auth, and overrides.
docs/codedocs/types.md	Overview of key exported types (environment, RequestOptions, protocols).
docs/codedocs/realtime-streaming.md	Concept/guide page for Listen/Speak realtime socket clients.
docs/codedocs/prerecorded-transcription.md	Concept/guide page for Listen v1 media transcription methods.
docs/codedocs/text-builder.md	Documentation for the TextBuilder helper and SSML conversion.
docs/codedocs/voice-agents.md	Documentation for realtime Agent v1 + reusable voice_agent surfaces.
docs/codedocs/guides/authentication-and-clients.md	Step-by-step guide for auth and choosing sync vs async clients.
docs/codedocs/guides/live-transcription.md	Step-by-step guide for realtime transcription flows.
docs/codedocs/guides/text-to-speech-workflows.md	Step-by-step guide for REST vs streaming TTS usage.
docs/codedocs/guides/management-and-automation.md	Guide for Manage + voice_agent + self_hosted automation workflows.
docs/codedocs/api-reference/deepgram-client.md	API reference for root clients and shared configuration types.
docs/codedocs/api-reference/listen.md	API reference for Listen REST + websocket surfaces.
docs/codedocs/api-reference/speak.md	API reference for Speak REST + websocket surfaces.
docs/codedocs/api-reference/read.md	API reference for Read text analysis methods.
docs/codedocs/api-reference/manage.md	API reference for administrative/manage endpoints.
docs/codedocs/api-reference/auth.md	API reference for token granting.
docs/codedocs/api-reference/agent.md	API reference for agent websocket + think model discovery.
docs/codedocs/api-reference/helpers.md	API reference for TextBuilder and transport utilities/protocols.
docs/codedocs/api-reference/voice-agent-self-hosted.md	API reference for voice_agent assets + self_hosted credentials.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-27T14:18:48Z

+
+Use Listen v1 if you need the older websocket surface and its broader batch-style query options. Use Listen v2 if your application is conversational and benefits from turn-aware events.
+
+" "Listen v2"]}>


The <Tabs ...> opening tag is malformed (" "Listen v2"]}>), which will likely break MDX rendering and prevent the tabbed example from displaying. Replace it with a valid <Tabs> element (and ensure it encloses the <Tab> blocks).

Suggested change

" "Listen v2"]}>

<Tabs items={["Listen v1", "Listen v2"]}>

Copilot · 2026-04-27T14:18:48Z

+Source: `src/deepgram/core/request_options.py`
+
+```python
+class RequestOptions(TypedDict total=False):


This snippet shows invalid Python syntax for defining a TypedDict: class RequestOptions(TypedDict total=False): is missing the comma after TypedDict (and in the actual codebase it’s class RequestOptions(typing.TypedDict, total=False):). Update the example to match valid Python and the real implementation.

Suggested change

class RequestOptions(TypedDict total=False):

class RequestOptions(typing.TypedDict, total=False):

Copilot · 2026-04-27T14:18:49Z

+with client.listen.v1.connect(model="nova-3" encoding="linear16", sample_rate=16000) as connection:
+    ...


This Python example is syntactically invalid: connect(model="nova-3" encoding=...) is missing a comma between the model and encoding keyword arguments.

Copilot · 2026-04-27T14:18:49Z

+with client.speak.v1.connect(model="aura-2-asteria-en" encoding="linear16", sample_rate=24000) as connection:
+    connection.on(EventType.MESSAGE, lambda message: print(type(message).__name__))


This Python example is syntactically invalid: connect(model="aura-2-asteria-en" encoding=...) is missing a comma between the model and encoding keyword arguments.

Copilot · 2026-04-27T14:18:49Z

+
+## Installation
+
+" "pipx"]}>


The opening <Tabs ...> tag appears to be corrupted (" "pipx"]}>) which will likely break MDX/markdown rendering for the installation tabs. Replace this line with a valid <Tabs> opening element (and ensure it wraps the subsequent <Tab> blocks).

Suggested change

" "pipx"]}>

<Tabs values={["pip", "uv", "poetry", "pipx"]}>

Copilot · 2026-04-27T14:18:52Z

+project_id = "PROJECT_ID"
+
+projects = client.manage.v1.projects.list()
+keys = client.manage.v1.projects.keys.list(project_id=project_id status="active")


This Python example is syntactically invalid: keys.list(project_id=project_id status="active") is missing a comma between the project_id and status keyword arguments.

Suggested change

keys = client.manage.v1.projects.keys.list(project_id=project_id status="active")

keys = client.manage.v1.projects.keys.list(project_id=project_id, status="active")

Copilot · 2026-04-27T14:18:52Z

+                time.sleep(0.01)
+        connection.send_close_stream(ListenV2CloseStream(type="CloseStream"))
+
+    threading.Thread(target=producer daemon=True).start()


This thread creation call is missing a comma between keyword arguments: threading.Thread(target=producer daemon=True) is invalid Python. It should pass target and daemon as separate keyword args.

Suggested change

threading.Thread(target=producer daemon=True).start()

threading.Thread(target=producer, daemon=True).start()

Copilot · 2026-04-27T14:18:53Z

+with client.speak.v1.connect(model="aura-2-asteria-en" encoding="linear16", sample_rate=24000) as connection:
+    audio = []


This Python example is syntactically invalid: connect(model="aura-2-asteria-en" encoding=...) is missing a comma between the model and encoding keyword arguments.

Copilot · 2026-04-27T14:18:53Z

+            provider=AgentV1SettingsAgentListenProvider_V1(type="deepgram" model="nova-3")
+        ),
+        think=ThinkSettingsV1(
+            provider=ThinkSettingsV1Provider_OpenAi(type="open_ai" model="gpt-4o-mini"),
+            prompt="Keep answers brief.",
+        ),
+        speak=SpeakSettingsV1(
+            provider=SpeakSettingsV1Provider_Deepgram(type="deepgram" model="aura-2-asteria-en")


This Python example is syntactically invalid: ThinkSettingsV1Provider_OpenAi(type="open_ai" model="gpt-4o-mini") is missing a comma between the type and model keyword arguments.

Suggested change

provider=AgentV1SettingsAgentListenProvider_V1(type="deepgram" model="nova-3")

),

think=ThinkSettingsV1(

provider=ThinkSettingsV1Provider_OpenAi(type="open_ai" model="gpt-4o-mini"),

prompt="Keep answers brief.",

),

speak=SpeakSettingsV1(

provider=SpeakSettingsV1Provider_Deepgram(type="deepgram" model="aura-2-asteria-en")

provider=AgentV1SettingsAgentListenProvider_V1(type="deepgram", model="nova-3")

),

think=ThinkSettingsV1(

provider=ThinkSettingsV1Provider_OpenAi(type="open_ai", model="gpt-4o-mini"),

prompt="Keep answers brief.",

),

speak=SpeakSettingsV1(

provider=SpeakSettingsV1Provider_Deepgram(type="deepgram", model="aura-2-asteria-en")

Copilot · 2026-04-27T14:18:53Z

+### Streaming Example
+
+```python
+with client.listen.v2.connect(model="flux-general-en" encoding="linear16", sample_rate=16000) as connection:


This Python example is syntactically invalid: connect(model="flux-general-en" encoding=...) is missing a comma between the model and encoding keyword arguments.

Suggested change

with client.listen.v2.connect(model="flux-general-en" encoding="linear16", sample_rate=16000) as connection:

with client.listen.v2.connect(model="flux-general-en", encoding="linear16", sample_rate=16000) as connection:

docs: add auto-generated code documentation

4b8790d

Copilot AI review requested due to automatic review settings April 27, 2026 14:10

enesgules requested a review from lukeocodes as a code owner April 27, 2026 14:10

Copilot started reviewing on behalf of enesgules April 27, 2026 14:11 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add auto-generated code documentation#698

docs: add auto-generated code documentation#698
enesgules wants to merge 1 commit intodeepgram:mainfrom
enesgules:codedocs/auto-generated

enesgules commented Apr 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Copilot AI Apr 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Use Listen v1 if you need the older websocket surface and its broader batch-style query options. Use Listen v2 if your application is conversational and benefits from turn-aware events.

		" "Listen v2"]}>

	class RequestOptions(TypedDict total=False):
	class RequestOptions(typing.TypedDict, total=False):

		with client.listen.v1.connect(model="nova-3" encoding="linear16", sample_rate=16000) as connection:
		...

		with client.speak.v1.connect(model="aura-2-asteria-en" encoding="linear16", sample_rate=24000) as connection:
		connection.on(EventType.MESSAGE, lambda message: print(type(message).__name__))

	keys = client.manage.v1.projects.keys.list(project_id=project_id status="active")
	keys = client.manage.v1.projects.keys.list(project_id=project_id, status="active")

	threading.Thread(target=producer daemon=True).start()
	threading.Thread(target=producer, daemon=True).start()

		with client.speak.v1.connect(model="aura-2-asteria-en" encoding="linear16", sample_rate=24000) as connection:
		audio = []

	with client.listen.v2.connect(model="flux-general-en" encoding="linear16", sample_rate=16000) as connection:
	with client.listen.v2.connect(model="flux-general-en", encoding="linear16", sample_rate=16000) as connection:

Conversation

enesgules commented Apr 27, 2026

Auto-generated Code Documentation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants