feat(python): audio-intelligence v1 — intents

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

@@ -0,0 +1,43 @@
+# Intent Recognition (Audio Intelligence v1)
+
+Detect speaker intents from audio to understand what speakers are trying to accomplish.
+
+## What it does
+
+When `intents=True` is set, Deepgram analyses the transcript to identify speaker intentions — such as requesting information, expressing agreement, making a complaint, or giving instructions. This is valuable for call-centre routing, automated ticket classification, and conversational analytics.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `intents` | `True` | Enable intent recognition |
+| `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...
+
+Intent segments: 2
+  Intents: informing — "Yeah, as much as it's worth celebrating the 50th"
+  Intents: explaining — "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/audio-intelligence/v1/intents/example.py

@@ -0,0 +1,43 @@
+"""
+Recipe: Intent Recognition (Audio Intelligence v1)
+====================================================
+Demonstrates detecting speaker intents in audio content.
+
+When intents=True is set, Deepgram identifies the intentions behind
+what speakers say — e.g., requesting information, expressing agreement,
+making a complaint. This is useful for call-centre routing, automated
+ticket categorisation, or conversational analytics.
+"""
+
+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,
+        intents=True,  # <-- THIS enables intent recognition.
+    )
+
+    if response.results and response.results.channels:
+        transcript = response.results.channels[0].alternatives[0].transcript
+        print(f"Transcript: {transcript[:150]}...")
+
+    # Intents appear in response.results.intents.segments
+    if hasattr(response.results, "intents") and response.results.intents:
+        segments = getattr(response.results.intents, "segments", [])
+        print(f"\nIntent segments: {len(segments)}")
+        for seg in segments[:5]:
+            text = getattr(seg, "text", "")
+            detected = getattr(seg, "intents", [])
+            intent_names = [getattr(i, "intent", "") for i in detected]
+            print(f"  Intents: {', '.join(intent_names)} — \"{text[:60]}\"")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,17 @@
+import subprocess
+from pathlib import Path
+
+def test_example_runs():
+    """Runs the intents 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"