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