SIGN IN SIGN UP

docs: target Context7 benchmark gaps in Python skills [no-ci] (#699)

## Summary

Closes the four largest gaps in the Context7 benchmark for
`/deepgram/deepgram-python-sdk`. Current score: **88.8/100** (mean
across 10 standardized prompts). The 4 weakest prompts account for ~97
of the 112 missing points; this PR addresses each one specifically.

## What's broken (Context7 evaluator quotes)

| # | Prompt | Score | What's missing |
|---|---|---|---|
| 1 | Voice agent dynamic adjustment + stream restart/pause | **66** |
"lacks specific guidance or API methods for dynamically adjusting
transcription parameters during an active connection or for
intelligently managing stream restarts and pauses beyond basic error
events" |
| 2 | Live streaming with interim results display | **71** | "all
examples show `interim_results=False`, which is the opposite of what's
needed, and none demonstrate how to differentiate between interim and
final results or how to handle the display logic" |
| 5 | Diarization + word-level timings combined | **83** | "lacks a
specific, complete code example showing how to enable both diarization
and word-level timings together in a single request" |
| 8 | Async URL transcription + retrieve final result | **83** | "lacks
critical information about handling asynchronous results — doesn't
explain how to retrieve the final transcription when using async methods
or how to poll for results" |

## Changes

### `deepgram-python-voice-agent/SKILL.md` (+139 lines, prompt #1)

- **New "Dynamic mid-session adjustment" section** — runnable code for
every control message exposed by the Agent socket client:
- `send_update_prompt(AgentV1UpdatePrompt)` — swap LLM system prompt
mid-conversation
  - `send_update_speak(AgentV1UpdateSpeak)` — swap TTS voice
  - `send_update_think(AgentV1UpdateThink)` — swap LLM provider/model
  - `send_inject_agent_message(...)` — force agent to say something
  - `send_inject_user_message(...)` — inject user input
  - `send_keep_alive(...)` — idle keep-alive
- Server reply event names noted for each (PromptUpdated, SpeakUpdated,
ThinkUpdated, InjectionRefused)
  - Async equivalents
- **New "Stream lifecycle & recovery" section** — KeepAlive loop on
idle, pause/resume audio, reconnect after disconnect with conversation
history replay via `AgentV1SettingsAgentContext`, `EventType.CLOSE` /
`EventType.ERROR` handling

### `deepgram-python-speech-to-text/SKILL.md` (+103 lines, prompts #2 +
#8)

**Prompt #2:**
- Rewrote the WebSocket quick-start to pass `interim_results=True`,
`utterance_end_ms=1000`, `vad_events=True`
- Real overwrite-line display pattern showing interim results live and
committing the line on final
- New "Interim vs. final flag semantics" subsection on `is_final`,
`speech_final`, `from_finalize` distinctions

**Prompt #8:**
- New "Async / deferred result patterns" section explicitly
distinguishing **Python `async/await`** (sync-style, immediate result
via `AsyncDeepgramClient`) from **deferred via callback URL** (returns
`request_id` immediately, results POST'd to webhook later — no polling)
- Decision table mapping each pattern to when to use it
- Pointer to `examples/12-transcription-prerecorded-callback.py`

### `deepgram-python-audio-intelligence/SKILL.md` (+41 lines, prompt #5)

- New "Quick start — diarization with word-level timings" section
- One focused snippet: `diarize=True, smart_format=True, punctuate=True`
+ per-word iteration accessing `speaker`, `start`, `end`, `confidence`,
`punctuated_word`
- Per-word fields table
- `groupby`-by-speaker utterance pattern + pointer to `utterances=True`
/ `paragraphs=True` for pre-grouped views

## Expected lift

If every gap closes:
- Prompt 1: 66 → ~95 (+29)
- Prompt 2: 71 → ~95 (+24)
- Prompt 5: 83 → ~95 (+12)
- Prompt 8: 83 → ~95 (+12)

Total potential: **+77 / 1000** (across 10 prompts) = **88.8 → ~96.5**
benchmark score.

## After merge

Trigger Context7 refresh on `/deepgram/deepgram-python-sdk` to pull the
new content into the index, then re-run the benchmark to verify the
lift.
L
Luke Oliff committed
a232eb8c62df2da98cef13c71e33f0b3b78f1095
Parent: e1b01fe
Committed by GitHub <noreply@github.com> on 4/27/2026, 4:14:07 PM