AGENTS.md

Agents

Fern SDK Regeneration

Overview

This SDK is generated by Fern. Most files under src/deepgram/ are auto-generated and should not be edited directly. Some files have manual patches and are listed in .fernignore to prevent the generator from overwriting them.

When a new Fern generator release is available, we prepare the repo so the generator can overwrite previously-frozen files, then re-apply manual patches after reviewing the diff.

Freeze classification rules

Every entry in .fernignore falls into one of two categories. The comment above each entry in .fernignore indicates which category it belongs to, but when in doubt, apply these rules:

Never unfreeze (permanently frozen)

These files are entirely hand-written — they have no Fern-generated counterpart. The generator would delete or replace them with something unrelated. They must stay in .fernignore at all times.

How to identify:

• The file was created by us, not by Fern (e.g., src/deepgram/client.py, custom tests, helpers, transport layer)
• The file is a doc, config, or folder we maintain independently (README, CHANGELOG, .github, examples, etc.)
• The file lives outside src/deepgram/ in a hand-maintained location (e.g., .claude/, docs/)

Current permanently frozen files:

• src/deepgram/client.py — entirely custom (Bearer auth, session ID); no Fern equivalent
• src/deepgram/helpers/ — hand-written TextBuilder helpers
• src/deepgram/agent/v1/types/agent_v1history_content.py, src/deepgram/agent/v1/types/agent_v1history_function_calls.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_messages_item.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_messages_item_content.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_messages_item_content_role.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_messages_item_function_calls.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_messages_item_function_calls_function_calls_item.py — hand-written compatibility aliases preserving old public Agent History type imports after regen renames
• src/deepgram/agent/v1/requests/agent_v1history_content.py, src/deepgram/agent/v1/requests/agent_v1history_function_calls.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_messages_item.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_messages_item_content.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_messages_item_function_calls.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_messages_item_function_calls_function_calls_item.py — hand-written compatibility aliases preserving old public Agent History request-param imports after regen renames
• src/deepgram/types/create_key_v1request_one.py, src/deepgram/requests/create_key_v1request_one.py — hand-written compatibility aliases preserving the old public create-key request imports after the regen rename to CreateKeyV1Request
• src/deepgram/agent/v1/types/agent_v1settings_agent_context_listen_provider_v1.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_listen_provider_v2.py, src/deepgram/agent/v1/types/agent_v1settings_agent_context_listen_provider_v2language_hint.py, src/deepgram/agent/v1/types/agent_v1settings_agent_listen_provider_v1.py, src/deepgram/agent/v1/types/agent_v1settings_agent_listen_provider_v2.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_listen_provider_v1.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_listen_provider_v2.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context_listen_provider_v2language_hint.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_listen_provider_v1.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_listen_provider_v2.py — hand-written compatibility aliases for the 2026-05-14 spec dedup that consolidated AgentV1SettingsAgent[Context]ListenProviderV{1,2,V2LanguageHint} into top-level DeepgramListenProvider* types
• src/deepgram/transport_interface.py, src/deepgram/transport.py, src/deepgram/transports/ — custom transport layer
• tests/custom/test_agent_history.py — hand-written regression test for Agent History websocket payload parsing
• tests/custom/test_compat_aliases.py — hand-written regression test for backward-compatible alias imports after regen renames
• tests/custom/test_query_encoder.py — hand-written regression test that core/query_encoder.py coerces Python bools to lowercase "true"/"false" before urlencode so websocket query strings stay wire-correct
• tests/custom/test_text_builder.py, tests/custom/test_transport.py — hand-written tests
• tests/typecheck/compat_aliases.py — hand-written mypy assert_type coverage for backward-compatible alias TypedDicts
• tests/manual/ — manual standalone tests
• README.md, CHANGELOG.md, CONTRIBUTING.md, reference.md — docs
• CLAUDE.md, AGENTS.md, .claude/ — agent files
• .github/, docs/, examples/ — folders

Unfreeze for regen (temporarily frozen)

These files are Fern-generated but carry manual patches to fix issues in the generator output. We freeze them to protect our patches between regenerations, but unfreeze them before a regen so we can compare the new output against our patches.

How to identify:

• The file exists in Fern's output — if you removed it from .fernignore and ran the generator, Fern would produce a version of it
• Our version is a modified copy of what Fern generates (e.g., changed float to int, added optional defaults, broadened a Union type)

Current temporarily frozen files:

• src/deepgram/speak/v1/socket_client.py — optional message param defaults, broad exception catch
• src/deepgram/listen/v1/socket_client.py — same
• src/deepgram/listen/v2/socket_client.py — same + send_configure typing.Any/raw shim, response Union uses typing.Any instead of ListenV2ConfigureSuccess
• src/deepgram/agent/v1/socket_client.py — same + _sanitize_numeric_types
• src/deepgram/agent/v1/types/agent_v1settings_agent_context.py, src/deepgram/agent/v1/types/agent_v1settings_agent.py, src/deepgram/agent/v1/types/agent_v1settings.py, src/deepgram/agent/v1/requests/agent_v1settings_agent_context.py, src/deepgram/agent/v1/requests/agent_v1settings_agent.py, src/deepgram/agent/v1/requests/agent_v1settings.py — backward-compat patches for the 2026-05-05 Agent Settings schema restructure. These preserve callable AgentV1SettingsAgent(...), keep AgentV1Settings.agent accepting both that wrapper and agent_id strings, restore the legacy request TypedDict shapes, remap legacy messages=[...] / nested context=AgentV1SettingsAgentContext(messages=[...]) usage into the new context={"messages": [...]} wire shape, and keep read-side obj.messages access working.
• src/deepgram/agent/v1/types/agent_v1settings_audio_output.py — keeps audio.output.container typed as str for backward compatibility instead of the regenerated enum alias
• src/deepgram/core/query_encoder.py — coerces Python bools to lowercase "true"/"false" before they reach urllib.parse.urlencode (which would otherwise produce "True"/"False" via str() and break websocket query strings). Only the four */connect() paths call urlencode; HTTP raw clients hand params to httpx, which lowercases bools itself, so the patch is a no-op for the HTTP path. Once Fern's websocket codegen normalizes bools (or the spec types these as boolean end-to-end), this can be unfrozen.
• tests/wire/test_manage_v1_projects_keys.py — restored wire coverage for the legacy CreateKeyV1RequestOneParams request alias so future regens do not silently drop that compatibility check
• src/deepgram/__init__.py, src/deepgram/agent/__init__.py, src/deepgram/agent/v1/__init__.py, src/deepgram/agent/v1/types/__init__.py, src/deepgram/agent/v1/requests/__init__.py, src/deepgram/types/__init__.py, src/deepgram/requests/__init__.py — package __init__.py files carrying hand-applied legacy alias re-exports for CreateKeyV1RequestOne, AgentV1HistoryContent, AgentV1HistoryFunctionCalls, AgentV1SettingsAgentContextMessagesItemContent, AgentV1SettingsAgentContextMessagesItemFunctionCalls (and their *Params variants). Fern would otherwise regenerate these and strip the legacy entries. After unfreezing for the next regen and reviewing the new generated content, re-apply the legacy re-exports plus any genuine new entries Fern added.

Prepare repo for regeneration

1. Create a new branch off main named lo/sdk-gen-<YYYY-MM-DD>.
2. Push the branch and create a PR titled chore: SDK regeneration <YYYY-MM-DD> (empty commit if needed).
3. Read .fernignore and classify each entry using the rules above.
4. For each temporarily frozen file only:
   • Copy the file to <filename>.bak alongside the original.
   • In .fernignore, replace the original path with the .bak path. This protects our patched version from the generator while allowing Fern to overwrite the original.
5. Never touch permanently frozen entries. Leave them in .fernignore as-is.
6. Commit as chore: unfreeze files pending regen and push.
7. The branch is now ready for the Fern generator to push changes.

After regeneration

The .bak files are our manually-patched versions (protected by .fernignore). The original paths now contain the freshly generated versions. By comparing the two, we can see what the generator now produces vs what we had patched.

1. Diff each .bak file against the new generated version to understand what changed and whether our patches are still needed.
2. Re-apply any patches that are still necessary to the newly generated files.
3. In .fernignore, replace each .bak path back to the original path for any files that still need manual patches.
4. Remove .fernignore entries entirely for any files where the generator now produces correct output (patches no longer needed).
5. Delete all .bak files once review is complete.
6. Run tests (pytest) and linting (ruff check, mypy) to verify.
7. Commit as chore: re-apply manual patches after regen and push.