feat(python): audio-intelligence v1 — summarize

recipes/python/audio-intelligence/v1/summarize/README.md

@@ -0,0 +1,41 @@
+# Audio Summarization (Audio Intelligence v1)
+
+Generate a concise text summary of spoken audio content alongside the transcript.
+
+## What it does
+
+When `summarize="v2"` is set, Deepgram produces a brief summary of the audio content in addition to the full transcript. This is useful for automatically generating meeting notes, podcast highlights, call summaries, or any scenario where a quick overview of audio content is needed.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `summarize` | `"v2"` | Enable summarization (v2 is the current version) |
+| `model` | `"nova-3"` | Transcription model |
+| `smart_format` | `True` | Format numbers, dates, etc. |
+
+## Example output
+
+```
+Transcript: Yeah, as much as it's worth celebrating the 50th anniversary of the spacewalk...
+
+Summary: The discussion covers the 50th anniversary of the first spacewalk and how space technology has evolved significantly 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/audio-intelligence/v1/summarize/example.py

@@ -0,0 +1,37 @@
+"""
+Recipe: Audio Summarization (Audio Intelligence v1)
+=====================================================
+Demonstrates generating a concise text summary of spoken audio content.
+
+Summarization is applied as a transcription option — set summarize="v2"
+and the response includes a summary alongside the transcript. This is
+useful for meeting notes, podcast highlights, or call analysis.
+"""
+
+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,
+        summarize="v2",  # <-- THIS enables audio summarization.
+    )
+
+    if response.results and response.results.channels:
+        transcript = response.results.channels[0].alternatives[0].transcript
+        print(f"Transcript: {transcript[:150]}...")
+
+    # The summary is in response.results.summary
+    if hasattr(response.results, "summary") and response.results.summary:
+        short = getattr(response.results.summary, "short", "")
+        print(f"\nSummary: {short}")
+
+
+if __name__ == "__main__":
+    main()

recipes/python/audio-intelligence/v1/summarize/example_test.py

@@ -0,0 +1,17 @@
+import subprocess
+from pathlib import Path
+
+def test_example_runs():
+    """Runs the summarize example and verifies it produces output."""
+    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, "Output seems too short"