test: increasing unit test coverage to 95 percent

.coveragerc

@@ -0,0 +1,19 @@
+[run]
+branch = True
+source = deepgram
+# The SDK is almost entirely auto-generated by Fern. Coverage targets the
+# hand-maintainable request/transport logic; generated data models (types/,
+# requests/) and package plumbing are excluded so the metric reflects code
+# that actually carries logic.
+omit =
+    */types/*
+    */requests/*
+    */__init__.py
+    */version.py
+    # Unused generated SSE transport scaffolding (no endpoint uses server-sent
+    # events; only referenced lazily by an optional helper).
+    */core/http_sse/*
+
+[report]
+show_missing = True
+fail_under = 90

.fernignore

@@ -164,20 +164,29 @@ src/deepgram/core/query_encoder.py
 # Hand-written custom tests
 tests/custom/test_agent_history.py
 tests/custom/test_agent_update_listen.py
+tests/custom/test_client.py
+tests/custom/test_client_construction_and_helpers.py
 tests/custom/test_compat_aliases.py
+tests/custom/test_core_internals_branches.py
+tests/custom/test_core_utilities_coverage.py
 tests/custom/test_eot_thresholds_feature.py
+tests/custom/test_http_endpoints_coverage.py
+tests/custom/test_http_retry_coverage.py
 tests/custom/test_language_hint_compat.py
 tests/custom/test_language_hints_feature.py
 tests/custom/test_latency_report_stt_compat.py
 tests/custom/test_listen_v2_connect_wire.py
 tests/custom/test_listen_v2_regen_constraints.py
+tests/custom/test_logging_and_retry_branches.py
 tests/custom/test_query_encoder.py
 tests/custom/test_secure_logging.py
 tests/custom/test_socket_client_shims.py
 tests/custom/test_speak_v2_connect_wire.py
+tests/custom/test_speak_v2_coverage.py
 tests/custom/test_speak_v2_socket.py
 tests/custom/test_text_builder.py
 tests/custom/test_transport.py
+tests/custom/test_websocket_streaming_coverage.py
 tests/typecheck/compat_aliases.py
 
 # Wire test with restored compatibility coverage for legacy create-key request alias
@@ -219,6 +228,20 @@ AGENTS.md
 .claude
 .agents
 
+# Hand-written coverage configuration (branch coverage, scoped source, generated
+# models excluded, fail_under gate). No Fern counterpart. Deliberately kept out
+# of pyproject.toml, which Fern regenerates: freezing pyproject.toml would also
+# block generator dependency updates (see 5c1e845, where a pydantic-core bound
+# fix for issue #701 shipped as a pyproject.toml-only regen change).
+.coveragerc
+
+# Hand-added ignores for local coverage artifacts (.coverage, htmlcov/,
+# coverage.xml) on top of Fern's generated entries. Fern has regenerated this
+# file before (fdcce88, ad93815, 4bee463) and would strip them.
+# [temporarily frozen — unfreeze + re-diff before each regen, then re-apply the
+# three coverage lines]
+.gitignore
+
 # Folders to ignore
 .github
 docs

.github/workflows/ci.yml

@@ -1,6 +1,10 @@
 name: CI
 
-on: [push]
+on:
+  push:
+    branches: [main]
+    tags: ["**"]
+  pull_request:
 
 jobs:
   compile:
@@ -29,6 +33,9 @@ jobs:
         run: poetry run mypy tests/typecheck
   test:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
@@ -55,7 +62,39 @@ jobs:
           docker compose version
 
       - name: Test
-        run: poetry run pytest -rP .
+        run: poetry run pytest -rP --cov=deepgram --cov-branch --cov-report=xml --cov-report=term-missing .
+      - name: Generate code coverage summary
+        if: matrix.python-version == '3.13'
+        uses: irongut/CodeCoverageSummary@v1.3.0
+        with:
+          filename: coverage.xml
+          badge: true
+          format: markdown
+          hide_branch_rate: false
+          hide_complexity: false
+          indicators: true
+          output: both
+          thresholds: "75 90"
+      - name: Annotate coverage scope
+        if: matrix.python-version == '3.13'
+        run: |
+          {
+            echo ""
+            echo "> Scope: hand-maintained SDK logic. Fern-generated data models (\`types/\`, \`requests/\`), package \`__init__.py\` files, \`version.py\`, and the unused \`core/http_sse/\` scaffolding are excluded — see \`.coveragerc\`. Unscoped whole-package coverage is ~70%."
+          } >> code-coverage-results.md
+      # Fork PRs get a read-only GITHUB_TOKEN, so the Issues API returns 403 and
+      # no `permissions:` block can grant it back. Skip on forks and stay
+      # best-effort; the job summary below carries the same table with no token.
+      - name: Add coverage PR comment
+        if: matrix.python-version == '3.13' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        continue-on-error: true
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: code-coverage
+          path: code-coverage-results.md
+      - name: Write coverage to job summary
+        if: matrix.python-version == '3.13'
+        run: cat code-coverage-results.md >> $GITHUB_STEP_SUMMARY
 
   publish:
     needs: [compile, test]

.gitignore

@@ -3,3 +3,6 @@
 __pycache__/
 dist/
 poetry.toml
+.coverage
+htmlcov/
+coverage.xml

AGENTS.md

@@ -40,6 +40,7 @@ Current permanently frozen files:
 - `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
+- `.coveragerc` — hand-written coverage configuration (branch coverage on, scoped to `deepgram`, generated data models and package plumbing excluded, `fail_under` gate). Deliberately kept out of `pyproject.toml`, which Fern regenerates: freezing `pyproject.toml` would also block generator dependency updates (see `5c1e845`, where a `pydantic-core` bound fix for issue #701 shipped as a `pyproject.toml`-only regen change). No Fern counterpart, so it never needs unfreezing.
 - `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `reference.md` — docs
 - `CLAUDE.md`, `AGENTS.md`, `.claude/` — agent files
 - `.github/`, `docs/`, `examples/` — folders
@@ -53,6 +54,7 @@ How to identify:
 - 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:
+- `.gitignore` — Fern generates a baseline version and has regenerated it before (`fdcce88`, `ad93815`, `4bee463`). We hand-add the local coverage artifact ignores (`.coverage`, `htmlcov/`, `coverage.xml`). Before each regen, unfreeze and re-diff so Fern's own additions are picked up, then re-apply the three coverage lines.
 - `src/deepgram/speak/v1/socket_client.py` — optional message param defaults, broad exception catch
 - `src/deepgram/speak/v2/socket_client.py` — same (optional `send_flush`/`send_close` defaults, broad exception catch); new websocket TTS client added in the 2026-07-08 regen
 - `src/deepgram/listen/v1/socket_client.py` — same