How to Ingest PPTX into Chroma with EnConvert

import json
import os
import time

import chromadb
import requests
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

ENCONVERT_API_KEY = os.environ["ENCONVERT_API_KEY"]
HEADERS = {"X-API-Key": ENCONVERT_API_KEY}

# Step 1: Upload the PPTX (the multipart field is named "files")
# Each slide is converted to a "## Slide N: Title" Markdown section before chunking
with open("/path/to/your/architecture-overview.pptx", "rb") as f:
    upload = requests.post(
        "https://api.enconvert.com/v2/ingest/files",
        headers=HEADERS,
        files={
            "files": (
                "architecture-overview.pptx",
                f,
                "application/vnd.openxmlformats-officedocument.presentationml.presentation",
            )
        },
        timeout=60,
    )
upload.raise_for_status()
job_id = upload.json()["job_id"]

# Step 2: Poll until the job completes
while True:
    status_response = requests.get(
        f"https://api.enconvert.com/v2/ingest/{job_id}",
        headers=HEADERS,
        timeout=30,
    )
    status_response.raise_for_status()
    job = status_response.json()
    if job["status"] == "completed":
        break
    if job["status"] in ("failed", "canceled"):
        raise RuntimeError(job.get("error_message") or f"Ingest job {job['status']}")
    time.sleep(2)

# Step 3: Download the JSONL output, one chunk per line
# The signed URL expires after 15 minutes. Plain GET, no API key.
jsonl_response = requests.get(job["output_url"], timeout=60)
jsonl_response.raise_for_status()

chunks = [
    json.loads(line)
    for line in jsonl_response.content.decode("utf-8").split("\n")
    if line.strip()
]
print(f"Loaded {len(chunks)} chunks ready for embedding")
print("Sections:", sorted({chunk["metadata"]["section"] for chunk in chunks}))

# Step 4: Connect to Chroma and create or open the collection
client = chromadb.PersistentClient(path="./chroma_db")

embedding_function = SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

collection = client.get_or_create_collection(
    name="pptx_chunks",
    embedding_function=embedding_function,
)

# Step 5: Add each chunk to Chroma with its metadata preserved
# headings_path is a list and can be empty, so join it into one string
# (Chroma does not accept empty lists as metadata values)
collection.add(
    ids=[chunk["id"] for chunk in chunks],
    documents=[chunk["content"] for chunk in chunks],
    metadatas=[
        {
            "section": chunk["metadata"]["section"],
            "headings_path": " > ".join(chunk["metadata"]["headings_path"]),
            "chunk_index": chunk["metadata"]["chunk_index"],
            "title": chunk["metadata"]["title"],
            "source_url": chunk["metadata"]["source_url"],
        }
        for chunk in chunks
    ],
)
print(f"Added {len(chunks)} chunks to Chroma")

# Step 6: Similarity search narrowed to one section by a metadata filter
# Replace with a section printed above. Slide sections look like "Slide 3: Title",
# and speaker notes are their own "Notes" section.
SECTION = "Slide 3: Service Authentication"

results = collection.query(
    query_texts=["how do services authenticate with each other"],
    n_results=3,
    where={"section": SECTION},
    include=["documents", "metadatas", "distances"],
)

for doc, meta, distance in zip(
    results["documents"][0], results["metadatas"][0], results["distances"][0]
):
    print(f"{meta['headings_path']} (distance {distance:.3f})")
    print(doc[:200])