feat: add a simple, verb-first Python API for all media types

[jdye64]

Description

Adds nemo_retriever.simple, a clean, user-facing Python API that reads like plain English and hides every implementation detail behind a handful of verbs. The goal is that a user immediately understands what happens when they call something, without needing to know about run modes, Ray, NIM endpoints, OCR/ASR, embedding models, or the vector store.

Import it as:

from nemo_retriever import simple as nr

Every verb works across all supported media types — documents (PDF, Word, PowerPoint), plain text, web pages (HTML), images, audio, and video — auto-detecting how to read each file. A source can be a single file, a folder, a wildcard pattern, or a list of any of those.

The verbs (the API options)

Read content out of your files:

• extract(source) — read anything and return everything found inside (text, tables, charts, pictures, transcribed speech).
• extract_documents(source) — PDFs, Word, PowerPoint.
• extract_text(source) — plain-text files.
• extract_web_pages(source) — saved HTML pages.
• extract_images(source) — pictures and scans.
• extract_audio(source) — audio recordings (transcribed to text).
• extract_video(source) — videos (on-screen text + spoken words).

Make content searchable and use it:

• ingest(source, *, into=None) — read files and make them searchable; into="a-name" saves a named library.
• search(index, question, *, limit=10) — find the passages that best match a question.
• ask(index, question, *, model) — get an answer written from your own content.

Discoverability:

• MEDIA_TYPES / supported_media() — enumerate every supported file type in plain language.

The facade is a thin, dependency-light layer that delegates to the existing create_ingestor / Retriever engine via lazy imports, so importing it adds no new import-time cost.

Design principles applied:

• Verb names and parameters contain no implementation details — descriptions say what happens, not how.
• Sensible defaults are chosen for the user so a first call just works.
• MEDIA_TYPES is covered by a test asserting it stays in sync with the engine's supported file extensions, so media coverage cannot silently drift.
• The API lives in its own nemo_retriever.simple module rather than the top-level namespace, to avoid colliding with the existing nemo_retriever.ingest subpackage.

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

  

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.