[CUST-43]: Deepgram/Assembly to gladia migration guide

[Karamouche]

Summary by CodeRabbit

• Documentation
  • Added migration guides for switching real-time speech-to-text from Deepgram and from AssemblyAI to Gladia, with installation, client setup, session flow, parameter mappings, usage examples, and error-handling for Python and TypeScript.
  • Updated Documentation navigation: added new migration pages and introduced a "Gladia V2" group that reorganizes existing migration entries.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds two migration guides (AssemblyAI → Gladia and Deepgram → Gladia) and updates documentation navigation to include these pages and group existing migration pages under a new "Gladia V2" group in docs.json.

Changes

Cohort / File(s)	Summary
Migration Documentation chapters/migrations/from-deepgram.mdx, chapters/migrations/from-assembly.mdx	Added two migration guides with install steps (Python/TypeScript), client initialization examples for source providers and Gladia, parameter mapping tables (provider → Gladia) with JSON config examples, session start/send-audio/read-transcripts procedures, event/error mappings, and Python/TypeScript code samples.
Navigation Configuration docs.json	Updated Documentation → Migrations: added "chapters/migrations/from-deepgram" and "chapters/migrations/from-assembly"; removed top-level "chapters/live-stt/migration-from-v1" and "chapters/pre-recorded-stt/migration-from-v1" from the main list and re-added them inside a new group object { "group": "Gladia V2", "expanded": true, "pages": [...] }.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify accuracy of parameter mapping tables and JSON examples.
• Confirm code samples compile/run for both Python and TypeScript contexts.
• Validate docs.json structure and navigation ordering.

Suggested reviewers

• sboudouk

Poem

🐇 I hopped through pages, nibbling code and clue,
Switched streams from old to shiny new.
Tokens, chunks, and events in tow,
Transcripts bloom where breezes blow.
A joyful thump — migration complete!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main changes: adding migration guides from Deepgram and Assembly to Gladia with new documentation files and updated navigation structure.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/deepgram-rt-migration

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3745368 and b853ac0.

📒 Files selected for processing (1)

• chapters/migrations/from-deepgram.mdx (1 hunks)

🧰 Additional context used

🪛 GitHub Check: Mintlify Validation (gladia-95) - vale-spellcheck

chapters/migrations/from-deepgram.mdx

[warning] 2-2: chapters/migrations/from-deepgram.mdx#L2
Did you really mean 'realtime'?

---

[warning] 2-2: chapters/migrations/from-deepgram.mdx#L2
Did you really mean 'Deepgram'?

---

[warning] 2-2: chapters/migrations/from-deepgram.mdx#L2
Did you really mean 'Gladia'?

---

[warning] 3-3: chapters/migrations/from-deepgram.mdx#L3
Did you really mean 'realtime'?

---

[warning] 3-3: chapters/migrations/from-deepgram.mdx#L3
Did you really mean 'Deepgram's'?

---

[warning] 3-3: chapters/migrations/from-deepgram.mdx#L3
Did you really mean 'Gladia's'?

---

[warning] 4-4: chapters/migrations/from-deepgram.mdx#L4
Did you really mean 'Deepgram'?

---

[warning] 7-7: chapters/migrations/from-deepgram.mdx#L7
Did you really mean 'realtime'?

---

[warning] 7-7: chapters/migrations/from-deepgram.mdx#L7
Did you really mean 'Deepgram'?

---

[warning] 7-7: chapters/migrations/from-deepgram.mdx#L7
Did you really mean 'Gladia'?

---

[warning] 13-13: chapters/migrations/from-deepgram.mdx#L13
Did you really mean 'SDKs'?

---

[warning] 13-13: chapters/migrations/from-deepgram.mdx#L13
Did you really mean 'realtime'?

---

[warning] 15-15: chapters/migrations/from-deepgram.mdx#L15
Did you really mean 'Deepgram'?

---

[warning] 29-29: chapters/migrations/from-deepgram.mdx#L29
Did you really mean 'Gladia'?

---

[warning] 47-47: chapters/migrations/from-deepgram.mdx#L47
Did you really mean 'Deepgram'?

---

[warning] 58-58: chapters/migrations/from-deepgram.mdx#L58
Did you really mean 'Deepgram'?

---

[warning] 65-65: chapters/migrations/from-deepgram.mdx#L65
Did you really mean 'Gladia'?

---

[warning] 89-89: chapters/migrations/from-deepgram.mdx#L89
Did you really mean 'Deepgram'?

---

[warning] 89-89: chapters/migrations/from-deepgram.mdx#L89
Did you really mean 'Gladia'?

---

[warning] 91-91: chapters/migrations/from-deepgram.mdx#L91
Did you really mean 'Gladia'?

---

[warning] 93-93: chapters/migrations/from-deepgram.mdx#L93
Did you really mean 'Gladia'?

---

[warning] 106-106: chapters/migrations/from-deepgram.mdx#L106
Did you really mean 'bit_depth'?

---

[warning] 107-107: chapters/migrations/from-deepgram.mdx#L107
Did you really mean 'sample_rate'?

---

[warning] 109-109: chapters/migrations/from-deepgram.mdx#L109
Did you really mean 'language_config'?

---

[warning] 109-109: chapters/migrations/from-deepgram.mdx#L109
Did you really mean 'code_switching'?

---

[warning] 110-110: chapters/migrations/from-deepgram.mdx#L110
Did you really mean 'messages_config'?

---

[warning] 111-111: chapters/migrations/from-deepgram.mdx#L111
Did you really mean 'receive_partial_transcripts'?

---

[warning] 112-112: chapters/migrations/from-deepgram.mdx#L112
Did you really mean 'receive_final_transcripts'?

---

[warning] 114-114: chapters/migrations/from-deepgram.mdx#L114
Did you really mean 'endpointing'?

---

[warning] 115-115: chapters/migrations/from-deepgram.mdx#L115
Did you really mean 'maximum_duration_without_endpointing'?

🔇 Additional comments (5)

chapters/migrations/from-deepgram.mdx (5)

1-7: Clear structure and introduction. The frontmatter and introductory text effectively set expectations for a low-friction migration path. Well done.

---

11-41: Well-organized SDK installation instructions. The parallel CodeGroup layout makes it easy for users to compare and select the appropriate commands. Structure is clear and consistent.

---

43-83: Clear client initialization examples. Both Python and TypeScript examples follow expected SDK patterns. The parallel structure makes migration straightforward.

---

125-295: Verify method signatures and event names against Gladia SDK. The session lifecycle and event-handling patterns look reasonable, but method names and type imports should be verified:

Python side (lines 149, 181, 257-273):

• gladia_client.live_v2() method exists and returns a session object
• session.send_audio(audio_chunk) is the correct method signature
• Type imports (LiveV2WebSocketMessage, LiveV2InitResponse, LiveV2EndedMessage) exist in the SDK
• Event names ("message", "started", "ended", "error") are correct

TypeScript side (lines 153, 185, 277-294):

• gladiaClient.liveV2() and startSession(gladiaConfig) methods exist
• session.sendAudio(audioChunk) is the correct method signature
• Event names and callback signatures match the SDK

Please cross-reference these method signatures and event names with the official Gladia SDK documentation to ensure they are current and accurate.

---

1-295: Static analysis warnings are mostly false positives. The vale-spellcheck tool flagged brand names (Deepgram, Gladia), acronyms (SDKs), and API parameter names as spelling errors. These are not actionable issues. However, if your style guide prefers "real-time" (hyphenated) instead of "realtime", consider standardizing that usage throughout the document.

Confirm if your documentation style guide has a preference for "real-time" vs. "realtime". If hyphenation is preferred, update all instances (lines 2, 3, 7, 13).

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

chapters/migrations/from-assembly.mdx (1)

304-328: Consider making the is_final filtering more explicit in code examples.

Both the Python and TypeScript Gladia event handler examples include comments noting that is_final should be used to filter partial vs. final transcripts, but the code examples don't show the actual conditional logic. Adding a simple if-statement would make the migration path clearer.

For example, in the TypeScript handler (lines 324–328), you could show:

gladiaSession.on("message", (message) => {
  if (message.data.is_final) {
    console.log("Final:", message.data.transcript);
  } else {
    console.log("Partial:", message.data.transcript);
  }
});

This makes the filtering pattern immediately clear to developers migrating from AssemblyAI, where partial and final events are separate. A similar example in the Python handler would be helpful as well.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4a599bc and 656966e.

📒 Files selected for processing (2)

• chapters/migrations/from-assembly.mdx (1 hunks)
• docs.json (1 hunks)

🔇 Additional comments (2)

docs.json (1)

113-122: All referenced migration guide files exist in the repository.

The navigation structure correctly references valid files. Both new migration guides (chapters/migrations/from-deepgram.mdx and chapters/migrations/from-assembly.mdx) and the v1 migration pages (chapters/live-stt/migration-from-v1.mdx and chapters/pre-recorded-stt/migration-from-v1.mdx) are present in the repository, so no broken navigation links will occur.

chapters/migrations/from-assembly.mdx (1)

100-109: Verify that internal documentation link paths and anchors are correct.

The parameter mapping table references internal documentation paths like /api-reference/v2/live/init#body-encoding and /chapters/live-stt/features/partial-transcripts. While the referenced features (POST /v2/live endpoint, partial transcripts, and code-switching) are confirmed to exist in Gladia's documentation, the exact internal path structure and anchor names (e.g., #body-encoding, #body-bit-depth) should be verified against the actual documentation file structure to ensure the links resolve correctly.