feat(python): speech-to-text v1 — keywords

recipes/python/speech-to-text/v1/keywords/README.md

@@ -0,0 +1,41 @@
+# Keyword Boosting (Speech-to-Text v1)
+
+Boost recognition accuracy for specific words or phrases that the model might otherwise miss or mishear.
+
+## What it does
+
+Keyword boosting lets you provide a list of words with intensity values. Positive intensity makes the model more likely to recognise that word; negative intensity suppresses it. This is especially useful for proper nouns, brand names, technical jargon, or uncommon words.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `keywords` | `"Deepgram:2"` | Word(s) to boost with intensifier (-10 to 10). Pass a list for multiple keywords. |
+| `model` | `"nova-3"` | Transcription model |
+| `smart_format` | `True` | Format numbers, dates, etc. |
+
+## Example output
+
+```
+Yeah, as much as it's worth celebrating the 50th anniversary of
+the spacewalk, it's also worth noting that we've come a long way
+since then...
+```
+
+## Prerequisites
+
+- Python 3.10+
+- Set `DEEPGRAM_API_KEY` environment variable
+- Install: `pip install -r recipes/python/requirements.txt`
+
+## Run
+
+```bash
+python example.py
+```
+
+## Test
+
+```bash
+pytest example_test.py -v
+```

recipes/python/speech-to-text/v1/keywords/example.py

@@ -0,0 +1,35 @@
+"""
+Recipe: Keyword Boosting (Speech-to-Text v1)
+=============================================
+Demonstrates the `keywords` feature, which boosts recognition accuracy
+for specific words or phrases.
+
+Keyword boosting is especially useful for proper nouns, brand names,
+or domain jargon that the model might not recognise out of the box.
+
+Format: "word:intensifier" where intensifier is a float (-10 to 10).
+Positive values boost the keyword; negative values suppress it.
+"""
+
+from deepgram import DeepgramClient
+
+AUDIO_URL = "https://dpgr.am/spacewalk.wav"
+
+
+def main():
+    client = DeepgramClient()  # reads DEEPGRAM_API_KEY from environment
+
+    response = client.listen.v1.media.transcribe_url(
+        url=AUDIO_URL,
+        model="nova-3",
+        smart_format=True,
+        keywords="Deepgram:2",  # <-- boost "Deepgram" recognition by intensifier 2.
+    )
+
+    if response.results and response.results.channels:
+        transcript = response.results.channels[0].alternatives[0].transcript
+        print(transcript)
+
+
+if __name__ == "__main__":
+    main()

recipes/python/speech-to-text/v1/keywords/example_test.py

@@ -0,0 +1,17 @@
+import subprocess
+from pathlib import Path
+
+def test_example_runs():
+    """Runs the keywords example and verifies it produces a transcript."""
+    example = Path(__file__).parent / "example.py"
+    result = subprocess.run(
+        ["python", str(example)],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, (
+        f"Example failed\nSTDOUT: {result.stdout}\nSTDERR: {result.stderr}"
+    )
+    assert result.stdout.strip(), "Example produced no output"
+    assert len(result.stdout.strip()) > 10, "Transcript seems too short"