[Example] 160 — LlamaIndex Audio Document Loader (Python)

[github-actions]

New example: LlamaIndex Audio Document Loader (Python)

Integration: LlamaIndex | Language: Python | Products: STT, Audio Intelligence

What this shows

A custom LlamaIndex BaseReader that transcribes audio via Deepgram nova-3 and turns recordings into LlamaIndex Documents. Audio Intelligence features (summarization, topics, sentiment, entity detection) are attached as document metadata. Includes a query mode that builds a VectorStoreIndex for RAG-powered Q&A over audio content.

Required secrets

OPENAI_API_KEY — needed only for query mode (LlamaIndex default LLM and embeddings). The core Deepgram transcription and document loading requires only DEEPGRAM_API_KEY.

---

Built by Engineer on 2026-03-31

[github-actions]

Code Review

Overall: APPROVED

Integration genuineness

✓ Pass. This example genuinely integrates with LlamaIndex. The code imports and implements BaseReader from llama_index.core.readers.base, creates proper Document objects with llama_index.core.schema.Document, and uses VectorStoreIndex.from_documents() for RAG-powered querying. The Deepgram SDK (DeepgramClient) is used for real pre-recorded transcription with Audio Intelligence features. .env.example lists both DEEPGRAM_API_KEY and OPENAI_API_KEY (the latter for LlamaIndex's default LLM/embeddings).

Code quality

• ✓ Official Deepgram Python SDK used (DeepgramClient, listen.v1.media.transcribe_url)
• ✓ No hardcoded credentials
• ✓ Good error handling — checks for missing OPENAI_API_KEY before query mode, uses getattr safely for optional Audio Intelligence fields
• ✓ Comments explain design decisions (why transcribe_url, why metadata is structured this way)

Documentation

• ✓ README clearly describes what you'll build (custom BaseReader with Audio Intelligence metadata for RAG)
• ✓ All env vars documented with where-to-find links
• ✓ Key parameters table present with descriptions
• ✓ Run instructions are exact and complete (both load and query modes)

Tests

• ✓ Credential check runs first before any imports that could fail
• ✓ Exit code 2 for missing credentials
• ✓ Four tests making real Deepgram API calls — STT, Document loading, Audio Intelligence metadata, LlamaIndex compatibility
• ✓ Meaningful assertions: transcript length, keyword matching, metadata field checks, confidence thresholds

---

✓ All checks pass. Marking review passed.

---

Review by Lead on 2026-03-31

[github-actions]

@deepgram-devrel — This PR has status:review-passed and passes all review criteria, but branch protection requires the e2e-api-check commit status which has not been posted. The PR cannot be merged by automation until the required status check is present. Recommended action: manually post the commit status or merge with admin privileges.

Sweep by Lead on 2026-03-31

[github-actions]

Code Review

Overall: APPROVED

Integration genuineness

✓ Pass — LlamaIndex integration is genuine:

• llama-index-core, llama-index-llms-openai, and llama-index-embeddings-openai are imported and used
• DeepgramAudioReader implements LlamaIndex's BaseReader interface with load_data()
• VectorStoreIndex.from_documents() builds a real RAG index from the Deepgram-produced Documents
• .env.example lists both DEEPGRAM_API_KEY and OPENAI_API_KEY (the latter for LlamaIndex's LLM/embeddings)
• Tests make real API calls to Deepgram and verify Documents work with LlamaIndex's VectorStoreIndex

Code quality

• ✓ Official Deepgram Python SDK used (DeepgramClient from deepgram)
• ✓ No hardcoded credentials
• ✓ Error handling: credential checks, proper exit codes
• ✓ Audio Intelligence features (summary, topics, sentiment, entities) correctly extracted from response

Documentation

• ✓ README describes concrete end result (custom BaseReader for RAG pipelines)
• ✓ All env vars documented with where-to-find links
• ✓ Key parameters table present
• ✓ Run instructions are exact and complete

Tests

• ✓ Credential check runs first (before any SDK imports), exits code 2
• ✓ Tests make real API calls to Deepgram (transcribe_url)
• ✓ Assertions verify transcript content, metadata, Audio Intelligence enrichment, and LlamaIndex Document compatibility
• ✓ Four distinct test cases covering: raw Deepgram STT, reader load_data, intelligence metadata, and Document indexability

Conventions

• ✓ .env.example present and complete
• ✓ Directory named 160-llamaindex-audio-loader-python — correct numbering
• ✓ PR title format correct: [Example] 160 — LlamaIndex Audio Document Loader (Python)
• ✓ Metadata block present in PR body

---

✓ All checks pass. Marking review passed.

---

Review by Lead on 2026-04-01

[github-actions]

Code Review

Overall: APPROVED

Integration genuineness

✓ Pass — LlamaIndex integration is real:

• llama_index.core is imported (BaseReader, Document, VectorStoreIndex)
• DeepgramAudioReader implements BaseReader.load_data() — the standard LlamaIndex reader contract
• Documents are created with proper metadata and work with VectorStoreIndex.from_documents()
• .env.example lists both DEEPGRAM_API_KEY and OPENAI_API_KEY (for LlamaIndex LLM/embeddings)
• Test makes real Deepgram API calls and validates LlamaIndex Document compatibility

Code quality

• ✓ Official Deepgram Python SDK (deepgram-sdk>=3.0.0)
• ✓ No hardcoded credentials
• ✓ Error handling: graceful getattr checks for optional Audio Intelligence features
• ✓ Clean separation: DeepgramAudioReader is a standalone, reusable class

Documentation

• ✓ README describes what you'll build (custom BaseReader for RAG pipelines)
• ✓ All env vars documented with where-to-find links
• ✓ Key parameters table present
• ✓ Run instructions are exact and complete

Tests

• ✓ Credential check runs first, exits 2 for missing creds
• ✓ Tests make real API calls (transcribe_url to Deepgram)
• ✓ Tests assert meaningful content (transcript keywords, metadata fields, Audio Intelligence data)
• ✓ Tests verify LlamaIndex Document compatibility (test_document_is_indexable)

Conventions

• ✓ .env.example present and complete
• ✓ Directory: 160-llamaindex-audio-loader-python ✓
• ✓ PR title: [Example] 160 — LlamaIndex Audio Document Loader (Python) ✓
• ✓ Metadata block present

---

✓ All checks pass. Marking review passed.

---

Review by Lead on 2026-04-01

[github-actions]

Code Review

Overall: APPROVED

Integration genuineness

Pass — LlamaIndex integration is genuine:

• Imports llama_index.core (BaseReader, VectorStoreIndex, Document)
• Implements a real BaseReader subclass with load_data() method
• Test verifies Documents work with VectorStoreIndex (LlamaIndex's core indexing API)
• .env.example lists OPENAI_API_KEY for LlamaIndex default LLM/embeddings
• Tests make real Deepgram API calls — no mocking

Code quality

• ✅ Official Deepgram Python SDK used (DeepgramClient)
• ✅ No hardcoded credentials
• ✅ Good error handling with getattr for optional Audio Intelligence fields
• ✅ Clean separation: reader class, load mode, query mode

Documentation

• ✅ README describes concrete end result (custom BaseReader for audio → RAG)
• ✅ All env vars documented with where-to-find links
• ✅ Key parameters table present
• ✅ Run instructions are exact and complete

Tests

• ✅ Credential check runs first, exits 2 for missing credentials
• ✅ Tests make real Deepgram API calls
• ✅ Tests assert meaningful content (transcript keywords, metadata fields, Document compatibility)
• ✅ Four distinct tests covering STT, loader, intelligence metadata, and indexability

Conventions

• ✅ .env.example present and complete
• ✅ Directory named 160-llamaindex-audio-loader-python
• ✅ PR title format correct
• ✅ Metadata block present in PR body

---

✓ All checks pass. Marking review passed.

---

Review by Lead on 2026-04-01

[github-actions]

Code Review

Overall: APPROVED

Integration genuineness

Pass — LlamaIndex integration is real and substantive:

• Imports BaseReader, Document, VectorStoreIndex from llama_index.core
• Implements the BaseReader.load_data() contract correctly
• Documents are indexed via VectorStoreIndex.from_documents() for RAG queries
• .env.example lists OPENAI_API_KEY (used by LlamaIndex default LLM/embeddings)
• Tests verify Documents are valid LlamaIndex Document objects

Code quality

• ✓ Official Deepgram Python SDK used (DeepgramClient)
• ✓ No hardcoded credentials
• ✓ Good error handling — checks for missing OPENAI_API_KEY before query mode
• ✓ Audio Intelligence features (summary, topics, sentiment, entities) properly extracted into metadata

Documentation

• ✓ README describes concrete end result (custom BaseReader for RAG pipelines)
• ✓ All env vars documented with where-to-find links
• ✓ Key parameters table present
• ✓ Run instructions are exact and complete
• ✓ "How it works" section explains the pipeline clearly

Tests

• ✓ Credential check runs first with exit code 2 for missing credentials
• ✓ Real API calls to Deepgram (not mocked)
• ✓ Meaningful assertions: transcript length, keyword content, metadata fields, Audio Intelligence presence, LlamaIndex Document type

Conventions

• ✓ .env.example present and complete
• ✓ Directory named 160-llamaindex-audio-loader-python — correct
• ✓ PR title format correct
• ✓ Metadata block present in PR body

---

✓ All checks pass. Marking review passed.

---

Review by Lead on 2026-04-01