ZerdaZerda

Tutorial: Getting Started

On this page

This tutorial walks through installing the package, loading your first document, and progressively exploring more of the API — building on Quickstart with more explanation at each step.

Step 1: Install

Bash
pip install zerda chardet pymupdf python-docx openpyxl beautifulsoup4 lxml requests

See Installation for the full optional-dependency breakdown.

Step 2: Load your first file

Create a small text file to experiment with:

Python · 2 lines
with open("hello.txt", "w") as f:
    f.write("Hello from zerda.document_loaders!\nThis is a second line.")

Load it:

Python · 9 lines
from zerda.document_loaders import TextLoader

loader = TextLoader("hello.txt")
docs = loader.load()

print(len(docs))                  # 1
print(docs[0].page_content)       # "Hello from zerda.document_loaders!\nThis is a second line."
print(docs[0].metadata)           # {'source': ..., 'loader_type': 'TextLoader', ...}
print(docs[0].doc_id)             # deterministic hash-derived ID

Step 3: Understand the LoadedDocument

Every loader returns the same shape of object:

Python · 5 lines
doc = docs[0]
doc.page_content   # the text
doc.metadata        # dict of source info
doc.doc_id           # stable content-derived ID
len(doc)             # character count

Try loading the same file again — the doc_id will be identical, because it's derived from content, not a timestamp or random value:

Python · 2 lines
docs2 = TextLoader("hello.txt").load()
assert docs[0].doc_id == docs2[0].doc_id

Step 4: Try a different format without changing your code

Swap in a PDF, CSV, or Word document — the pattern stays the same regardless of format:

Python · 10 lines
from zerda.document_loaders import CSVLoader

# contacts.csv:
# name,email
# Alice,alice@example.com
# Bob,bob@example.com

docs = CSVLoader("contacts.csv").load()
print(len(docs))              # 2 — one document per row
print(docs[0].page_content)   # "name: Alice\nemail: alice@example.com"

Step 5: Let AutoLoader pick the right loader for you

Instead of importing a specific loader class, use AutoLoader, which detects the format automatically:

Python · 5 lines
from zerda.document_loaders import AutoLoader

docs = AutoLoader.load("hello.txt")      # → TextLoader
docs = AutoLoader.load("contacts.csv")   # → CSVLoader
docs = AutoLoader.load("./")             # → DirectoryLoader (loads everything in cwd)

Step 6: Load a whole directory

Python · 5 lines
from zerda.document_loaders import DirectoryLoader

loader = DirectoryLoader(".", recursive=False, silent_errors=True)
docs = loader.load()
print(f"Loaded {len(docs)} documents from {loader.get_stats()['total_files']} files")

Next steps

Related pages