docs: add auto-generated code documentation

docs/codedocs/api-reference/agent.md

@@ -0,0 +1,72 @@
+---
+title: "Agent"
+description: "Reference for the realtime agent websocket and think-model discovery APIs."
+---
+
+The Agent domain is the runtime surface for realtime conversational sessions.
+
+## Imports
+
+```python
+from deepgram import DeepgramClient
+from deepgram.agent.v1.types import AgentV1Settings
+```
+
+Source files:
+
+- `src/deepgram/agent/v1/client.py`
+- `src/deepgram/agent/v1/socket_client.py`
+- `src/deepgram/agent/v1/settings/think/models/client.py`
+
+## `V1Client.connect`
+
+Import path: `client.agent.v1`
+
+```python
+connect(
+    *,
+    authorization: str | None = None,
+    request_options: RequestOptions | None = None,
+) -> Iterator[V1SocketClient]
+```
+
+## `V1SocketClient` Methods
+
+Source: `src/deepgram/agent/v1/socket_client.py`
+
+- `start_listening()`
+- `send_settings(message: AgentV1Settings) -> None`
+- `send_update_speak(message: AgentV1UpdateSpeak) -> None`
+- `send_inject_user_message(message: AgentV1InjectUserMessage) -> None`
+- `send_inject_agent_message(message: AgentV1InjectAgentMessage) -> None`
+- `send_function_call_response(message: AgentV1SendFunctionCallResponse) -> None`
+- `send_keep_alive(message: AgentV1KeepAlive | None = None) -> None`
+- `send_update_prompt(message: AgentV1UpdatePrompt) -> None`
+- `send_update_think(message: AgentV1UpdateThink) -> None`
+- `send_media(message: bytes) -> None`
+- `recv() -> V1SocketClientResponse`
+
+`V1SocketClientResponse` is a union of typed agent events such as `AgentV1ConversationText`, `AgentV1AgentThinking`, `AgentV1FunctionCallRequest`, `AgentV1Warning`, `AgentV1History`, plus raw `bytes` audio.
+
+## Think Model Discovery
+
+Import path: `client.agent.v1.settings.think.models`
+
+```python
+list(*, request_options: RequestOptions | None = None) -> AgentThinkModelsV1Response
+```
+
+This endpoint comes from `src/deepgram/agent/v1/settings/think/models/client.py` and lets you inspect supported think providers before composing agent settings.
+
+## Example
+
+```python
+with client.agent.v1.connect() as agent:
+    agent.send_settings(settings)
+    agent.send_media(b"...audio chunk...")
+    agent.start_listening()
+```
+
+## Implementation Note
+
+Before sending a Pydantic model, the socket client runs `_sanitize_numeric_types(...)`. That helper converts values such as `24000.0` into `24000` so integer-only API fields survive serialization correctly.

docs/codedocs/api-reference/auth.md

@@ -0,0 +1,49 @@
+---
+title: "Auth"
+description: "Reference for token generation in the Deepgram Python SDK."
+---
+
+The Auth domain is intentionally small. Its main job is to mint temporary access tokens from an API key.
+
+## Imports
+
+```python
+from deepgram import DeepgramClient
+```
+
+Source files:
+
+- `src/deepgram/auth/client.py`
+- `src/deepgram/auth/v1/client.py`
+- `src/deepgram/auth/v1/tokens/client.py`
+
+## `TokensClient.grant`
+
+Import path: `client.auth.v1.tokens`
+
+```python
+grant(
+    *,
+    ttl_seconds: float | None = OMIT,
+    request_options: RequestOptions | None = None,
+) -> GrantV1Response
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `ttl_seconds` | `float \| None` | API default, documented as 30 seconds | Lifetime for the generated JWT. |
+| `request_options` | `RequestOptions \| None` | `None` | Per-request headers, retries, and timeout. |
+
+## Example
+
+```python
+issuer = DeepgramClient(api_key="dg_server_key")
+token = issuer.auth.v1.tokens.grant(ttl_seconds=60)
+
+client = DeepgramClient(access_token=token.access_token)
+```
+
+## Notes
+
+- The generated docstring in `src/deepgram/auth/v1/tokens/client.py` states that the token carries `usage::write` permission for core voice APIs.
+- Tokens created here do not replace the Manage APIs for project administration.

docs/codedocs/api-reference/deepgram-client.md

@@ -0,0 +1,137 @@
+---
+title: "Deepgram Client"
+description: "Reference for the root sync and async clients, shared configuration, and request options."
+---
+
+The root client layer lives in `src/deepgram/client.py` and `src/deepgram/base_client.py`. Import these classes from `deepgram`.
+
+## Imports
+
+```python
+from deepgram import DeepgramClient, AsyncDeepgramClient, DeepgramClientEnvironment
+from deepgram.core.request_options import RequestOptions
+```
+
+## Classes
+
+### `DeepgramClient`
+
+Source: `src/deepgram/client.py`
+
+```python
+DeepgramClient(
+    *,
+    environment: DeepgramClientEnvironment = DeepgramClientEnvironment.PRODUCTION,
+    api_key: str | None = os.getenv("DEEPGRAM_API_KEY"),
+    headers: dict[str, str] | None = None,
+    timeout: float | None = None,
+    follow_redirects: bool | None = True,
+    httpx_client: httpx.Client | None = None,
+    logging: LogConfig | Logger | None = None,
+    access_token: str | None = None,
+    session_id: str | None = None,
+    transport_factory: callable | None = None,
+)
+```
+
+### `AsyncDeepgramClient`
+
+Source: `src/deepgram/client.py`
+
+```python
+AsyncDeepgramClient(
+    *,
+    environment: DeepgramClientEnvironment = DeepgramClientEnvironment.PRODUCTION,
+    api_key: str | None = os.getenv("DEEPGRAM_API_KEY"),
+    headers: dict[str, str] | None = None,
+    timeout: float | None = None,
+    follow_redirects: bool | None = True,
+    httpx_client: httpx.AsyncClient | None = None,
+    logging: LogConfig | Logger | None = None,
+    access_token: str | None = None,
+    session_id: str | None = None,
+    transport_factory: callable | None = None,
+)
+```
+
+## Constructor Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `environment` | `DeepgramClientEnvironment` | `DeepgramClientEnvironment.PRODUCTION` | Chooses HTTPS and WebSocket base URLs. |
+| `api_key` | `str \| None` | `DEEPGRAM_API_KEY` | Standard token-style credential for generated clients. |
+| `access_token` | `str \| None` | `None` | Forces bearer auth through the hand-written override layer. |
+| `session_id` | `str \| None` | auto-generated UUID | Sent as `x-deepgram-session-id` on REST and WebSocket calls. |
+| `headers` | `dict[str, str] \| None` | `None` | Extra shared headers. |
+| `timeout` | `float \| None` | `60` when using default clients | Base timeout in seconds. |
+| `follow_redirects` | `bool \| None` | `True` | Redirect handling for default `httpx` clients. |
+| `httpx_client` | `httpx.Client \| httpx.AsyncClient \| None` | generated default | Bring-your-own HTTP transport, pools, or proxies. |
+| `logging` | `LogConfig \| Logger \| None` | `None` | Shared SDK logging config. |
+| `transport_factory` | callable \| `None` | `None` | Global override for generated websocket transport calls. |
+
+## Domain Properties
+
+These properties are created lazily in `src/deepgram/base_client.py`.
+
+| Property | Return type | Import path |
+|----------|-------------|-------------|
+| `agent` | `AgentClient` / `AsyncAgentClient` | `deepgram.agent` |
+| `auth` | `AuthClient` / `AsyncAuthClient` | `deepgram.auth` |
+| `listen` | `ListenClient` / `AsyncListenClient` | `deepgram.listen` |
+| `manage` | `ManageClient` / `AsyncManageClient` | `deepgram.manage` |
+| `read` | `ReadClient` / `AsyncReadClient` | `deepgram.read` |
+| `self_hosted` | `SelfHostedClient` / `AsyncSelfHostedClient` | `deepgram.self_hosted` |
+| `speak` | `SpeakClient` / `AsyncSpeakClient` | `deepgram.speak` |
+| `voice_agent` | `VoiceAgentClient` / `AsyncVoiceAgentClient` | `deepgram.voice_agent` |
+
+## Supporting Types
+
+### `DeepgramClientEnvironment`
+
+Source: `src/deepgram/environment.py`
+
+```python
+class DeepgramClientEnvironment:
+    PRODUCTION: DeepgramClientEnvironment
+    AGENT: DeepgramClientEnvironment
+
+    def __init__(self, *, base: str, agent: str, production: str)
+```
+
+### `RequestOptions`
+
+Source: `src/deepgram/core/request_options.py`
+
+```python
+class RequestOptions(TypedDict total=False):
+    timeout_in_seconds: int
+    max_retries: int
+    additional_headers: dict[str, Any]
+    additional_query_parameters: dict[str, Any]
+    additional_body_parameters: dict[str, Any]
+    chunk_size: int
+```
+
+## Example
+
+```python
+from deepgram import DeepgramClient
+
+client = DeepgramClient(
+    access_token="TEMP_TOKEN",
+    session_id="call-17",
+    headers={"X-App-Name": "triage-worker"},
+)
+
+response = client.read.v1.text.analyze(
+    request={"text": "Customer wants to upgrade the subscription."},
+    intents=True,
+    request_options={"timeout_in_seconds": 15},
+)
+```
+
+## Related Pages
+
+- `/docs/api-reference/listen`
+- `/docs/api-reference/speak`
+- `/docs/client-lifecycle`

docs/codedocs/api-reference/helpers.md

@@ -0,0 +1,110 @@
+---
+title: "Helpers"
+description: "Reference for helper utilities such as TextBuilder and custom transport protocols."
+---
+
+This SDK ships a small but important helper surface: text assembly for TTS and transport protocols for custom WebSocket integrations.
+
+## Imports
+
+```python
+from deepgram.helpers import TextBuilder
+from deepgram.transport import install_transport, restore_transport
+from deepgram.transport_interface import SyncTransport, AsyncTransport
+```
+
+## `TextBuilder`
+
+Source: `src/deepgram/helpers/text_builder.py`
+
+```python
+class TextBuilder:
+    def text(self, content: str) -> TextBuilder
+    def pronunciation(self, word: str, ipa: str) -> TextBuilder
+    def pause(self, duration_ms: int) -> TextBuilder
+    def from_ssml(self, ssml_text: str) -> TextBuilder
+    def build(self) -> str
+```
+
+Related free functions:
+
+```python
+add_pronunciation(text: str, word: str, ipa: str) -> str
+ssml_to_deepgram(ssml_text: str) -> str
+```
+
+### Example
+
+```python
+from deepgram.helpers import TextBuilder
+
+text = (
+    TextBuilder()
+    .text("Take ")
+    .pronunciation("methotrexate", "mɛθəˈtrɛkseɪt")
+    .text(" weekly.")
+    .build()
+)
+```
+
+## Transport Utilities
+
+Source files:
+
+- `src/deepgram/transport.py`
+- `src/deepgram/transport_interface.py`
+
+### Signatures
+
+```python
+install_transport(*, sync_factory: callable | None = None, async_factory: callable | None = None) -> None
+restore_transport() -> None
+```
+
+### Protocols
+
+```python
+class SyncTransport(Protocol):
+    def send(self, data: Any) -> None
+    def recv(self) -> Any
+    def __iter__(self) -> Iterator
+    def close(self) -> None
+
+class AsyncTransport(Protocol):
+    async def send(self, data: Any) -> None
+    async def recv(self) -> Any
+    def __aiter__(self) -> Any
+    async def close(self) -> None
+```
+
+### Example
+
+```python
+from deepgram import DeepgramClient
+
+
+class MyTransport:
+    def __init__(self, url: str, headers: dict[str, str]):
+        self.url = url
+        self.headers = headers
+
+    def send(self, data):
+        ...
+
+    def recv(self):
+        ...
+
+    def __iter__(self):
+        yield from ()
+
+    def close(self):
+        pass
+
+
+client = DeepgramClient(api_key="dg_key", transport_factory=MyTransport)
+```
+
+## When To Use These Helpers
+
+- Use `TextBuilder` when pronunciation correctness matters.
+- Use transport helpers when you need to integrate the SDK with a non-default websocket layer or a controlled test environment.