From faad89bae697fb14109ea8b531d2172f9a87811d Mon Sep 17 00:00:00 2001 From: lukeocodes Date: Wed, 29 Apr 2026 12:31:45 +0100 Subject: [PATCH 1/2] chore: remove .claude/skills/ maintenance skills (moved to deepgram/agents) [no-ci] prepare-regen and review-regen are SDK-team workflow skills targeted at us, not at SDK users. They've been generalized and consolidated into the internal deepgram/agents repo (PR #16) where the SDK team installs them once and gets them across every SDK they touch. This SDK's user-facing skills under .agents/skills/ are unchanged -- those are for SDK consumers and stay where they are. See: https://github.com/deepgram/agents/pull/16 --- .claude/skills/prepare-regen.md | 20 -------------------- .claude/skills/review-regen.md | 22 ---------------------- 2 files changed, 42 deletions(-) delete mode 100644 .claude/skills/prepare-regen.md delete mode 100644 .claude/skills/review-regen.md diff --git a/.claude/skills/prepare-regen.md b/.claude/skills/prepare-regen.md deleted file mode 100644 index bd5c0569..00000000 --- a/.claude/skills/prepare-regen.md +++ /dev/null @@ -1,20 +0,0 @@ -# Prepare Repo for Fern SDK Regeneration - -Triggers: prepare regen, prepare for regeneration, prep for fern, new sdk gen, prepare sdk gen - -## Steps - -Read AGENTS.md for full context on the regeneration workflow and freeze classification rules. - -1. Fetch latest `main` and create a new branch: `lo/sdk-gen-` (use today's date). -2. Push the branch to origin. -3. Create an empty commit (`chore: initialize SDK regeneration branch`) if needed, then create a PR titled `chore: SDK regeneration `. -4. Read `.fernignore` and classify each entry using the rules in AGENTS.md: - - **Permanently frozen**: entirely hand-written, no Fern equivalent. NEVER touch these. - - **Temporarily frozen**: Fern-generated with manual patches. These get swapped. -5. For each **temporarily frozen** file only: - - Copy the file to `.bak` alongside the original. - - In `.fernignore`, replace the original path with the `.bak` path (protects our patch, lets Fern overwrite the original). -6. Stage the updated `.fernignore` and all `.bak` files. -7. Commit as `chore: unfreeze files pending regen` and push. -8. Report the PR URL and confirm the branch is ready for generator output. diff --git a/.claude/skills/review-regen.md b/.claude/skills/review-regen.md deleted file mode 100644 index 8511bca2..00000000 --- a/.claude/skills/review-regen.md +++ /dev/null @@ -1,22 +0,0 @@ -# Review Fern SDK Regeneration - -Triggers: review regen, review regeneration, diff regen, compare regen, post regen review - -## Steps - -Read AGENTS.md for full context on the regeneration workflow and freeze classification rules. - -1. Find all `.bak` files in the repo — these are our pre-regen manually-patched versions (protected by `.fernignore`). -2. For each `.bak` file, diff it against the corresponding newly generated file to show what changed. -3. Identify which manual patches are still needed (the `.bak` has changes the generator doesn't produce). -4. Present a summary of findings to the user, grouped by category: - - Patches no longer needed (generator now handles it) - - Patches still needed (must be re-applied) - - New changes from the generator worth noting -5. Wait for user direction on which patches to re-apply. -6. Re-apply confirmed patches to the generated files. -7. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches. -8. Remove `.fernignore` entries entirely for files where patches are no longer needed. -9. Delete all `.bak` files. -10. Run `ruff check --fix`, `mypy --ignore-missing-imports src/deepgram/`, and `pytest` to verify. -11. Commit as `chore: re-apply manual patches after regen` and push. From c7a3b7a4c72fba14abf640a5e62ac32b3f1f9207 Mon Sep 17 00:00:00 2001 From: lukeocodes Date: Wed, 29 Apr 2026 12:43:03 +0100 Subject: [PATCH 2/2] chore: also remove .agents/skills/deepgram-python-maintaining-sdk [no-ci] This was a duplicate of AGENTS.md content (its own footer admitted so) and is internal-facing. The maintenance workflow lives in deepgram/agents PR #16 now; AGENTS.md in this repo remains as the SDK-specific source of truth for frozen file lists and validation commands. --- .../deepgram-python-maintaining-sdk/SKILL.md | 84 ------------------- 1 file changed, 84 deletions(-) delete mode 100644 .agents/skills/deepgram-python-maintaining-sdk/SKILL.md diff --git a/.agents/skills/deepgram-python-maintaining-sdk/SKILL.md b/.agents/skills/deepgram-python-maintaining-sdk/SKILL.md deleted file mode 100644 index 21f14da2..00000000 --- a/.agents/skills/deepgram-python-maintaining-sdk/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: deepgram-python-maintaining-sdk -description: Use when regenerating this Python SDK with Fern, editing `.fernignore`, preparing the repo for a generator release, reconciling manually-patched files after regen, or deciding whether a file should be permanently frozen vs temporarily frozen. This SDK is Fern-generated - most files under `src/deepgram/` should NOT be edited directly. Triggers include "fern regen", "regenerate SDK", ".fernignore", "unfreeze", "re-apply patches", "SDK regeneration", "freeze classification", "generator release". ---- - -# Maintaining the Deepgram Python SDK - -This SDK is generated by [Fern](https://buildwithfern.com/). 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/transport_interface.py`, `src/deepgram/transport.py`, `src/deepgram/transports/` — custom transport layer -- `tests/custom/test_text_builder.py`, `tests/custom/test_transport.py` — hand-written tests -- `tests/manual/` — manual standalone tests -- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `reference.md` — docs -- `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/` — agent files (this skill lives under `.agents/`) -- `.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 (reflects the live `.fernignore` in this repo; treat `.fernignore` as the source of truth and re-check before starting a regen): - -- `src/deepgram/agent/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` — generator bugs in `construct_type` call convention and exception handling; broad `except Exception` catch for custom transports; optional control-message params on `send_keep_alive` / `send_close_stream` / etc.; agent client additionally carries `_sanitize_numeric_types` (float → int) for unknown WS message shapes. -- `src/deepgram/types/listen_v1response_results_utterances_item.py`, `...item_words_item.py`, and `...channels_item_alternatives_item_paragraphs_paragraphs_item.py` — manual `float` → `int` corrections for speaker / channel / num_words fields (waiting on internal-api-specs#205). - -Any other entries (previously frozen `listen_v1redact.py`, `listen/v1/client.py`, `listen/v2/client.py`, `tests/wire/test_listen_v1_media.py`, `wiremock/wiremock-mappings.json`) have been removed from `.fernignore` as Fern output improved. Read `.fernignore` directly before a regen rather than relying on this list staying perfectly current. - -## Prepare repo for regeneration - -1. **Create a new branch** off `main` named `lo/sdk-gen-`. -2. **Push the branch** and create a PR titled `chore: SDK regeneration ` (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 `.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 and linting**: - ```bash - pytest - ruff check - mypy - ``` -7. **Commit** as `chore: re-apply manual patches after regen` and push. - -## Source-of-truth note - -This skill is the canonical maintainer workflow. `AGENTS.md` in the repo root contains the same content for agents that look there first; keep the two in sync. If the procedure changes, update both.