# Agents

## Fern SDK Regeneration

### Overview

This SDK is generated by [Fern](https://buildwithfern.com/). Most files under `src/main/java/com/deepgram/` are auto-generated and should not be edited directly. Some files are hand-written or carry 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 or are maintained independently from Fern. 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, such as custom client wrappers or transport abstractions
- The file is a doc, config, build, or CI artifact we maintain independently
- The file lives outside the generated Java package tree or is a manually maintained test/example

Current permanently frozen files:

- `src/main/java/com/deepgram/DeepgramClient.java`, `src/main/java/com/deepgram/AsyncDeepgramClient.java`, `src/main/java/com/deepgram/DeepgramClientBuilder.java`, `src/main/java/com/deepgram/AsyncDeepgramClientBuilder.java` - custom wrapper entrypoints that add Bearer auth, session ID support, and custom transport behavior on top of Fern's generated API client
- `src/main/java/com/deepgram/core/transport/` - hand-written transport abstraction
- `build.gradle`, `settings.gradle`, `gradle/`, `gradlew`, `gradlew.bat`, `pom.xml`, `Makefile` - build and project configuration
- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENSE` - docs
- `src/test/` - manually maintained tests
- `examples/` - manually maintained examples
- `.editorconfig`, `.githooks/`, `.github/`, `.gitignore` - repo and CI configuration
- `target/` - build output
- `CLAUDE.md`, `AGENTS.md`, `.claude/` - agent files

Note: `.fernignore` also includes flat-path variants such as `src/main/java/DeepgramClient.java` as defensive entries for alternate local generation layouts. Those files do not currently exist in this repo checkout and should not be treated as current maintained source files.

#### 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

Current temporarily frozen files:

- `src/main/java/com/deepgram/core/ClientOptions.java` - preserves release-please version markers and correct SDK header constants that Fern currently overwrites; use the standard `.bak` swap/restore workflow during regen review

### 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 versus 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. For `src/main/java/com/deepgram/core/ClientOptions.java`, use the standard `.bak` restore flow if the generated output still overwrites the Deepgram SDK header constants and `// x-release-please-version` markers.
3. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches.
4. Remove `.fernignore` entries entirely for any files where the generator now produces correct output.
5. Delete all `.bak` files once review is complete.
6. Run checks (`./gradlew test`) to verify.
7. Commit as `chore: re-apply manual patches after regen` and push.