oriolrius.me Production RAGReference guide
Part 02·Foundations

Set Up the Workshop and Get Data In

Project setup with uv, credentials, and the loader layer that turns any file into Documents.

27 min read 17 sections Foundations

This is the only part of the guide that builds nothing intelligent. It covers roughly twenty minutes of the source course — 00:08:27 to 00:28:27 — and it produces two artefacts: a Python project that can call two model providers, and a loader layer that turns arbitrary files into the one data structure every later stage assumes.

In the mental model from Part 1, this part owns the first box of Phase A:

Figure 1Phase A (index): this Part covers Load
Original ASCII
PHASE A — INDEX
  Load ──► Split ──► [Contextualize] ──► Embed ──► Store + Index
   ▲
   └── you are here

It also lays down the substrate everything else stands on: credentials, the package manager, and the environment-loading discipline. None of it is glamorous. All of it is load-bearing — the metadata dict a loader attaches in this part is literally the citation the user sees in Part 6, and the .env you create here is the file every provider client in the remaining fourteen parts silently reads from.

Read this part once, do it once, and never think about it again. A setup you have to keep re-deciding is a setup that will eventually desync and cost you a debugging session in Part 8 that has nothing to do with retrieval.

Credentials before code

The course opens its hands-on track not in an editor but in two vendor consoles, and the ordering is the teaching point. An LLM application's first dependency is not a library, it is a secret. Nothing downstream — no embedding call, no chat call, no retrieval test — can be verified until a key exists. Write the code first and your first run fails for a reason that has nothing to do with your code.

You need at least two keys: one OpenAI, one Anthropic 00:09:31. The stated reason is not redundancy and not benchmarking.

"The point is that we should have at least a way to infer models." 00:09:31

The requirement is capability, not brand. The instructor is explicit that a different provider is fine and beside the point — the code is written against LangChain's provider integration packages, so swapping vendors later is an import plus a model-string change, not a rewrite. Two providers is simply what makes that swappability demonstrable in the smoke test you are about to write.

The two consoles differ in a way that matters operationally: the scope a key is bound to.

ProviderConsole pathKey scopeWhat you choose at creation
OpenAISettings → API keys → Create new secret keyProjectKey name + project (course uses Default project)
Anthropicplatform.claude.com → Manage → API keys → Create KeyWorkspaceKey name + workspace (default is fine with one workspace)

Procedure A — OpenAI key. Log in, go past the Dashboard / Docs / API tabs into Settings, open API keys, click Create new secret key, name it, pick the project (Default project in the course), click Create secret key, then copy the value 00:08:30.

Procedure B — Anthropic key. Go to platform.claude.com, left nav → Manage → API keys. That page lists your organization and any existing keys. Click Create Key, give it a name, choose the workspace, confirm 00:08:30.

The toolchain: uv, and only uv

uv is the package and project manager for the entire guide. Not pip, not Poetry, not conda. The course treats this as already-decided and never revisits it. The instructor demos on macOS and runs a curl installer without reading the URL aloud, so the command below is the canonical reconstruction from the uv docs rather than a quotation.

Five commands cover everything you will do:

CommandWhat it does
uv initScaffolds a project in the current directory: pyproject.toml, main.py, README.md, .python-version, .gitignore, and a git repo
uv venvCreates the project virtual environment at .venv
source .venv/bin/activateActivates it (macOS/Linux form; Windows differs)
uv add <pkg>Resolves the dependency, writes it into pyproject.toml, updates uv.lock, installs it
uv run <script>Runs a script inside the project environment, syncing first — no manual activation needed

Procedure C — bootstrap the project.

bash
# Install uv if you don't have it (macOS/Linux; Windows uses a PowerShell installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

# The course's project is named langc-course
# (audio says "lang course"; pyproject.toml says name = "langc-course")
mkdir langc-course && cd langc-course
ls                      # confirm it is empty first
uv init                 # scaffold
uv venv                 # create .venv
source .venv/bin/activate

uv add langchain langchain-core langgraph \
       langchain-openai langchain-anthropic python-dotenv

touch .env
uv run main.py          # prints "Hello from langc-course!" from the scaffold

That last line is worth running before you touch anything. It proves the interpreter, the venv and the scaffold all agree, and it gives you a known-good baseline to break 00:11:34.

Note that uv venv + source .venv/bin/activate are strictly redundant given that every execution in the course is uv run main.py — uv run resolves and syncs the environment for you. The instructor does both anyway, and it is a reasonable habit: an activated venv makes the environment visible to your shell, your editor's interpreter picker, and to any tool that doesn't know about uv.

Windows is the one platform caveat in the chapter, and the instructor flags it twice: both the uv install command and the venv activation command differ, and neither is shown 00:09:31, 00:10:33.

Core packages versus integration packages

The six-package install list is not arbitrary — it reflects LangChain 1.x's packaging model, which is the reason provider-swapping is cheap.

PackageLayerWhy it's there
langchainFrameworkThe umbrella package
langchain-coreFrameworkProvider-agnostic abstractions: Runnables, messages, prompts, Document
langgraphFrameworkGraph/state-machine orchestration
langchain-openaiIntegrationShips ChatOpenAI, OpenAIEmbeddings
langchain-anthropicIntegrationShips ChatAnthropic
python-dotenvUtilityReads .env into the process environment

The core stays vendor-neutral; each vendor lives in its own langchain-<vendor> distribution. That is why ChatOpenAI is imported from langchain_openai and ChatAnthropic from langchain_anthropic, and never from langchain. Swapping providers is an import change plus a model string — which is exactly the asymmetry Part 4 will make into a rule: the generation model is swappable, the embedding model is not.

langgraph goes in on day one even though nothing in this guide uses it until Part 15. That is a deliberate signal: graph-based orchestration is treated as part of the baseline stack rather than an add-on you bolt on when the pipeline gets agentic. Its version is printed in the smoke test alongside langchain-core.

Those six are the bootstrap. By the end of this part you will have added three more: langchain-community (the loaders), pypdf (the PDF parser behind PyPDFLoader), and bs4 (BeautifulSoup, which WebBaseLoader parses HTML with — it ships in the repo's pins but is never installed on camera). The rest of production-course-main-code/pyproject.toml, which pins name = "langc-course" and requires-python = ">=3.12", is a table of contents for the build:

Pinned packageArrives inFor
langchain-community>=0.4.1this partDocument loaders
pypdf>=6.6.2this partPyPDFLoader's parser
bs4>=0.0.2this partWebBaseLoader's HTML parsing
langchain-chroma>=1.1.0Part 4The vector store
rank-bm25>=0.2.2Part 6Lexical half of hybrid search
langchain-ollama>=1.0.1Parts 9–10Local models, when the bill matters
langgraph-checkpoint-sqlite>=3.0.3LaterLangGraph agent state
fastapi>=0.129.0, uvicorn>=0.40.0Part 11Serving the pipeline
pytest>=9.0.2Part 13The test suite

Secrets: .env, load_dotenv(), and the ordering rule

Create .env and put the two keys in it:

text
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Then, in code:

Python
# production-course-main-code/main.py, lines 1-4
from dotenv import load_dotenv
from importlib.metadata import version

load_dotenv()

"So all the keys are now available for us to use." 00:11:34

Notice what is not done anywhere in the repo: the keys are never passed to ChatOpenAI(...) or ChatAnthropic(...) as arguments. The provider SDKs read OPENAI_API_KEY and ANTHROPIC_API_KEY straight out of the process environment at client construction time.

The corresponding hygiene rule is never spoken on camera but is written into the repo's .gitignore, which leads with it:

text
# Environment variables — NEVER commit these
.env

# Python
__pycache__/
*.pyc
*.pyo
.venv/
venv/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db
.claude
chroma_db/

Three of those entries are doing real work beyond tidiness. .env is the obvious one. .venv/ keeps a few hundred megabytes of platform-specific binaries out of history. chroma_db/ keeps a generated vector index out of git — and that one is a genuine production instinct: the index is derived data, it is large, it is machine-specific, and it must be rebuildable from source documents plus code. If you ever find yourself wanting to commit an index, what you actually want is a reproducible ingest script.

Your .env will grow. LangSmith tracing variables arrive in Part 7, Supabase/pgvector credentials in Part 10, and API auth secrets in Parts 11–12. Set the habit now.

The smoke test, and its four-line acceptance criterion

Here is the entire deliverable of the setup chapter — 32 lines, verbatim from the repo:

Python
# production-course-main-code/main.py
from dotenv import load_dotenv
from importlib.metadata import version

load_dotenv()

core_version = version("langchain-core")
lg_version = version("langgraph")
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic


print(f"langchain-core version: {core_version}")
print(f"langgraph version: {lg_version}")


def main():

    # Test openai
    llm = ChatOpenAI(model_name="gpt-4o-mini", temperature=0)
    response = llm.invoke("Say 'setup complete!' in one word")
    print(f"Response from ChatOpenAI: {response}")

    # Test anthropic
    llm_anthropic = ChatAnthropic(model="claude-sonnet-4-5-20250929", temperature=0)
    response_anthropic = llm_anthropic.invoke("Say 'setup complete!' in one word")
    print(f"Response from ChatAnthropic: {response_anthropic}")

    print("Setup complete!")


if __name__ == "__main__":
    main()

There is more instruction packed into those 32 lines than the running time suggests.

Version checking that actually works. The intuitive way fails:

Python
# DOES NOT WORK — many LangChain 1.x packages export no __version__
from langchain_core import __version__ as core_version
from langgraph import __version__ as lg_version

The working way is the stdlib:

Python
from importlib.metadata import version
core_version = version("langchain-core")   # hyphen: DISTRIBUTION name
lg_version   = version("langgraph")

The instructor calls this "just a minor change" 00:13:38, but the generalisable rule is real: ask the package metadata for a distribution's version, not the module for a __version__ attribute.

Why bother printing versions at all? Because in an ecosystem moving this fast, behaviour differs by major version, and a guide written against 1.x will not match a reader on 2.x. The course hedges its own numbers repeatedly, characterising langchain-core and langgraph only as "over 1.0" and dating the 1.0 stable release to a couple of months before recording 00:14:38. The versions actually pinned in the repo are langchain-core 1.2.7 and langgraph 1.0.7. Treat printed versions as a snapshot you record, not a target you pin to.

"Of course, by the time you're watching this video, this could be different." 00:14:38

.predict() is dead. The instructor catches himself mid-sentence writing the OpenAI call 00:12:37: .predict() is the legacy pre-LCEL, string-in/string-out API. The Runnable interface in LangChain 1.x is .invoke(), with .batch(), .stream() and async variants alongside it. Every model call for the rest of this guide — and every chain in Part 1's LCEL composition — is .invoke().

.invoke() returns a message object, not a string. The script prints the whole response, which dumps an AIMessage-style repr: the text plus token usage, model id and stop reason. The text itself lives at .content, which the instructor points out on screen 00:14:38. This trips anyone expecting a str, and it will matter again in Part 1's chain, where StrOutputParser() exists precisely to unwrap it.

Smoke-test hygiene. The prompt — "Say 'setup complete!' in one word" — is deliberately trivial and byte-identical across both providers. The point is not the answer; it is that the round trip works: key found, network reachable, model id valid, response parsed. Keeping the prompt identical means any difference in outcome is a provider difference, not a prompt difference.

Cost and determinism defaults. gpt-4o-mini is chosen explicitly to keep the check cheap 00:12:37 — the course's first appearance of a cost-consciousness theme that returns hard in Parts 8 and 9. Both clients use temperature=0, which is the sane default for a verification script and, as Part 5 will argue, for grounded RAG generation generally.

Four more things about this file that the audio never mentions:

  • The imports at lines 8–9 sit after executable statements at lines 6–7. Stylistically

ugly; practically, it means a missing langchain-anthropic fails after the version banner has already printed, which reads like a version problem and isn't one.

  • The version prints are at module scope, not inside main(). They fire on import, so any

other module that imports main gets the banner as a side effect.

  • There is no os.getenv guard. The script requires both keys and gives you a raw SDK

auth error if either is missing. A one-provider setup fails the smoke test in a way that doesn't say "you are missing a key".

  • The Anthropic model id is dated (claude-sonnet-4-5-20250929) and will eventually be

retired. Expect to bump it; a 404 on that string is a model-lifecycle event, not a bug in your setup.

Run it:

bash
uv run main.py

The acceptance test. Your environment is ready when one run of main.py prints four things: two version strings, one non-error OpenAI response, one non-error Anthropic response, and the final Setup complete! line. Anything less and you are not done, no matter how right the code looks.

Why a loader layer exists at all

With a working environment, the pipeline can start. The first stage is loading, and its justification is one sentence: an LLM only knows what you put in its context window, and that context has to come from somewhere 00:15:35.

"Large language models need context, and context comes from data, documents and so forth." 00:15:35

The input category is raw files: PDF, TXT, HTML, DOCX, CSV and anything else you have lying around 00:15:35 — five named formats with nothing in common. Five parsers, five APIs, five error shapes, five metadata conventions. The loader layer's entire job is to collapse that heterogeneity into one shape so that every downstream stage — splitters, embedders, vector stores, retrievers — only ever has to speak one type.

The second point is about build-versus-buy. LangChain already ships the wrappers, so you should not be hand-rolling PDF parsers. But note what "wraps" means literally: LangChain provides the uniform interface and delegates the actual parsing to a third-party library it does not install for you. That single fact explains both of the live failures in this chapter, and it is the reason the section below on missing dependencies exists.

The Document object

Every loader returns a list of Document objects, and every Document has exactly two parts:

FieldTypeContents
page_contentstrThe extracted text
metadatadictProvenance attached by the loader: source, page number, author, creation date, …

That is the whole contract. It is also the escape hatch — a Document is just a data class, so you can construct one yourself with whatever metadata you like:

Python
# production-course-main-code/document_loaders.py:74-89
def doc_structure():
    doc = Document(
        page_content="This is a sample document.",
        metadata={
            "source": "manual_creation.txt",
            "author": "Paulo",
            "length": 30,
            "tags": ["sample", "test"],
            "created_at": "2024-06-01",
        },
    )

    print("Document Structure:")
    print(f"  page_content (type): {type(doc.page_content)}")
    print(f"  page_content: {doc.page_content}")
    print(f"  metadata: {doc.metadata}")

It is imported from core, not community: from langchain_core.documents import Document.

Note "tags": ["sample", "test"] — as far as LangChain is concerned the metadata dict takes arbitrary keys and non-scalar values. Whether your vector store accepts them is a separate question, and most do not: Chroma, which Part 4 uses, only stores scalar metadata values, so flatten lists to a delimited string or a set of boolean flags before you index. This hand-construction path is exactly what Part 5 reaches for when a loader can't give you the fields you need.

The universal two-line pattern

Every loader in LangChain has the same shape, and that sameness is the reason the abstraction is worth learning at all:

Python
loader = SomeLoader(source)   # 1. instantiate with the source
docs   = loader.load()        # 2. call .load() → list[Document]

That's it. Path, URL, or directory goes in the constructor; .load() comes out as documents 00:17:37. The sameness is not a convention either — it is enforced by the base class. langchain_core.document_loaders.BaseLoader.load() is literally return list(self.lazy_load()), and subclasses are told to implement lazy_load() and leave load() alone. Every loader you will ever meet is therefore a generator plus a one-line materialiser.

Here is the catalogue as the course presents it:

LoaderSourceNotes
TextLoaderA .txt pathThe simplest possible case; 1 file → 1 Document
PyPDFLoaderA PDF path1 page → 1 Document
DirectoryLoaderA folder pathA dispatcher: takes glob + loader_cls
WebBaseLoaderOne URL or severalFetches and extracts HTML
UnstructuredLoaderComplex/mixed formatsThe escape hatch (MD, TXT and others)

The demo PDF's own on-screen text names three more that the audio never discusses — CSVLoader (row-based documents), JSONLoader (jq-style extraction) and YouTubeLoader (transcripts). They exist; they are simply out of scope for the course, and the two-line pattern applies to them unchanged.

Hands-on 1: TextLoader, and the first missing dependency

The chapter's live coding happens in a dedicated file, document_loaders.py. The first import fails:

bash
uv add langchain-community

The document loaders live in langchain-community, not in langchain-core. The instructor justifies the install by saying the community package is where the text splitters live 00:21:44 — that reason is wrong and should not be propagated. Text splitters ship in langchain-text-splitters (pinned separately in the repo at 1.1.0). The action is correct; the stated cause is not. What langchain_community actually gives you here is langchain_community.document_loaders.

The file's imports:

Python
# production-course-main-code/document_loaders.py:1-15
import os
import tempfile
from pathlib import Path
from langchain_core.documents import Document
from langchain_community.document_loaders import (
    TextLoader,
    WebBaseLoader,
    DirectoryLoader,
    PyPDFLoader,
)
from bs4 import BeautifulSoup

from dotenv import load_dotenv

load_dotenv()

Importing this module prints a warning before it runs a line of your code: USER_AGENT environment variable not set, consider setting it to identify your requests. It comes from langchain_community.utils.user_agent, and it is worth understanding rather than muting, because it is an ordering trap of exactly the same species as load_dotenv(). web_base.py builds its default_header_template at import time, so the environment variable has to already be set when line 5 executes — and load_dotenv() here is line 15. Putting USER_AGENT in .env therefore does nothing for this file; you get DefaultLangchainUserAgent on every request, which some sites reject outright. Export it in the shell (or set os.environ["USER_AGENT"] above the loader imports), or pass an explicit header_template= to the loader and stop relying on the global.

And the first demo:

Python
# production-course-main-code/document_loaders.py:18-42
def load_text_file():
    # Create a temporary text file for demonstration
    with tempfile.NamedTemporaryFile(delete=False, suffix=".txt") as temp_file:
        temp_file.write(
            b"Hello, this is a sample text file.\nThis file is used to demonstrate the TextLoader."
        )
        temp_file_path = temp_file.name

    try:
        # Load the text file using TextLoader
        loader = TextLoader(temp_file_path)
        documents = loader.load()

        print(f"Loaded {len(documents)} document(s)")
        print(f"Content preview: {documents[0].page_content[:100]}...")
        print(f"Metadata: {documents[0].metadata}")

        # Print the loaded documents
        # for doc in documents:
        #     print("Document Content:")
        #     print(doc)
        #     print(doc.page_content)
    finally:
        # Clean up the temporary file
        os.remove(temp_file_path)

The commented-out block at the bottom is not dead code — it is the first pass, preserved. The instructor's initial version printed the whole Document object so you could see its shape, then he replaced it with three projected facts: len(documents), a 100-character content preview, and the metadata dict 00:24:50. Both are worth doing, in that order: dump the object once to learn the type, then project the fields you actually care about.

Result: one text file → exactly one Document 00:24:50, and its metadata has exactly one key:

Python
{'source': '/tmp/tmpop0y38v3.txt'}

That is all TextLoader attaches — its implementation ends with metadata = {"source": str(self.file_path)} and yields a single Document. The instructor also reads a creation timestamp off his screen 00:23:48; the pinned langchain-community 0.4.1 does not produce one, so do not design around it. The lesson generalises: print the metadata dict once, from your own version, before you build anything on top of it.

Two smaller things: NamedTemporaryFile(delete=False) genuinely leaks the file, which is why the finally: os.remove(...) exists and is not optional. And the preview length is [:100] — the transcript's "the first 1,00 or 100 characters" 00:24:50 is a mis-speak; the code is authoritative.

Hands-on 2: PyPDFLoader, and the behaviour that breaks naive code

Same two lines, different loader — and that sameness is the lesson 00:25:52. But first, the second missing dependency:

bash
uv add pypdf

LangChain wraps pypdf; it does not bundle it. Expect the identical pattern for every other parser-backed loader (pymupdf for PyMuPDFLoader, unstructured for the Unstructured family). Missing parser dependencies are the norm in this layer, not the exception.

Python
# production-course-main-code/document_loaders.py:92-99
def pdf_loader(pdf_path: str):
    loader = PyPDFLoader(pdf_path)
    documents = loader.load()

    print(f"Loaded {len(documents)} document(s) from PDF")
    for i, doc in enumerate(documents):
        print(f"Document {i+1} Content Preview: {doc.page_content[:100]}...")
        print(f"Metadata: {doc.metadata}")

Called as pdf_loader("./docs/langchain_demo.pdf") — the repo's active entrypoint, with the other four demos commented out. The fixture is a self-generated 3-page, 4.5 KB PDF whose own text happens to list the loader catalogue and five best practices; Part 3 will reuse it, because page 2 carries the pangram "The quick brown fox jumps over the lazy dog" as chunking test data.

The metadata is auto-populated by the parser. Running the repo code against the demo PDF gives exactly this for page one:

Python
{
    'producer': 'PyPDF',
    'creator': 'PyPDF',
    'creationdate': '2026-02-02T21:45:08+00:00',
    'source': './docs/langchain_demo.pdf',
    'total_pages': 3,
    'page': 0,
    'page_label': '1',
}

Seven fields, three of which are traps.

The fixture is quietly complicit. The demo PDF's own worked example, printed on its page 1, formats a citation as print(f"Page: {doc.metadata['page']}") — the 0-indexed field. The sample code you are reading while you learn the API already has the bug in it.

The repo's own loop repeats it differently: it prints Document {i+1} from enumerate, producing a human-friendly 1-based counter that has no relationship to the page key sitting right beside it in the same output. If you copy that loop, do not use the printed number as a citation.

source is the string you typed, not a path. The dict above says './docs/langchain_demo.pdf' because that is the literal argument the entrypoint passed. It is not resolved, not made absolute, and not normalised. Two ingest scripts that spell the same file differently produce two different citation strings, two different metadata-filter values, and no way to deduplicate. Normalise once at ingest — str(Path(p).resolve()) — and do it before the first embedding, because Part 4 will show that you can only filter on what you committed at index time.

producer and creator are not provenance. Both say PyPDF here for a mundane reason: the instructor generated the demo PDF with pypdf, so the library that wrote the file and the library that read it are the same. These fields describe tooling, not authorship. Do not surface them to users as "the document's creator," and do not build filters on them expecting a meaningful signal 00:27:57.

Metadata is parser-dependent, not truth. It tells you what the pipeline saw, which is exactly what you want for debugging — and exactly what you must not confuse with what the document is.

Choosing a PDF loader

PDFs are where loader choice actually matters, because PDF is a layout format pretending to be a document format. The course gives a three-way comparison 00:18:41:

LoaderSpeedMetadataBest for
PyPDFLoaderFastBasicSimple PDFs. Start here.
PyMuPDFLoaderFastestGoodHigh volume; the instructor's all-rounder pick
UnstructuredPDFLoaderSlowestRichest / most detailedTables and complex layouts

The real lesson is the shape of that curve: you are buying fidelity with latency, and you pick a point per use case rather than once forever.

"If you have documents that have tables and layouts, then UnstructuredPDFLoader is going to be your best bet." 00:19:41

The course starts with PyPDFLoader deliberately and says so:

"Depending on your use case, you can switch to something else." 00:19:41

A caveat the course does not state but Part 16 will: none of these three loaders solve tables and charts, they only degrade less badly. UnstructuredPDFLoader gives you more structure to work with; a chart is still destroyed by text extraction. The vision-based answer is multimodal retrieval, and it is a different architecture, not a different loader.

Web loading

WebBaseLoader takes one URL, or several at once. The repo's runnable version was never executed on camera:

Python
# production-course-main-code/document_loaders.py:45-54
def web_loader():
    loader = WebBaseLoader(
        "https://en.wikipedia.org/wiki/Web_scraping", bs_kwargs={"parse_only": None}
    )
    documents = loader.load()

    print(f"Loaded {len(documents)} document(s) from web")
    print(f"Source: {documents[0].metadata.get('source', 'N/A')}")
    print(f"Content length: {len(documents[0].page_content)} characters")
    print(f"Preview: {documents[0].page_content[:200]}...")

The slide showed three pages of example.com and the instructor hedged that they are fetched in parallel 00:19:41. Reading the shipped loader settles it, and the answer is a genuine production detail:

Directory loading, glob, and lazy_load()

DirectoryLoader is not really a loader, it is a dispatcher. It takes three parameters 00:20:41:

  1. the path — the folder to walk;
  2. the glob — which files to match, including how deep to recurse (**/*.pdf for all PDFs

in all subdirectories);

  1. loader_cls — which loader class parses each matched file.

"This is what we call glob pattern — filters files." 00:20:41

The repo's version pairs it with the other thing the audio never mentions: lazy_load().

Python
# production-course-main-code/document_loaders.py:57-71
def lazy_loader():

    # Create temp directory with sample files
    with tempfile.TemporaryDirectory() as tmpdir:
        # Create sample files
        for i in range(5):
            path = Path(tmpdir) / f"doc_{i}.txt"
            path.write_text(f"This is document {i}. It contains sample content.")

        loader = DirectoryLoader(tmpdir, glob="*.txt", loader_cls=TextLoader)

        print("Initialized lazy loader for directory:", tmpdir)
        for doc in loader.lazy_load():
            print("Document Content Preview:", doc.page_content[:50], "...")
            print("Metadata:", doc.metadata["source"])

Five files, a 50-character preview each. The important line is loader.lazy_load():

MethodReturnsMemoryUse when
.load()list[Document] — everything, materialisedO(corpus)Small, known sets; you need len() or random access
.lazy_load()A generator, one Document at a timeO(1) per documentLarge ingests; you are streaming straight into a splitter/embedder

Because the loop above discards each doc after printing, nothing accumulates in RAM. That is the property to sell: for a 50,000-document ingest, .load() builds the entire corpus in memory before the first chunk is ever embedded; .lazy_load() lets you pipeline load → split → embed → store one document at a time. The demo PDF's own "Best Practices" page says the same thing: "For large document sets, use lazy_load() instead of load()."

One more knob worth knowing before your first large directory: use_multithreading=False by default, with max_concurrency=4 when you turn it on. Parsing is the bottleneck in most ingests, so this is usually the cheapest speed-up available — and, like every concurrency switch, the fastest way to turn an ordering assumption into a bug.

Metadata is the citation substrate

This is the part of the loader layer that pays off latest and matters most. The demo PDF spells it out on its own page 2, which is a nice accident:

"Loaders preserve metadata like page numbers, file paths, and sources. Use this information for citations."

The chain runs: loader attaches metadata → splitter propagates it → vector store persists it → retriever returns it → the formatter renders it as [n] source inside the context string the model reads. Part 1 established that sources travel inside the context, not out of band; Part 3 will show that split_documents() propagates parent metadata while split_text() destroys it; Part 4 will show that you can only filter on metadata you committed at index time.

That gives you a rule with an uncomfortable consequence:

And one habit worth adopting immediately, at zero cost:

Print doc.metadata['source'] next to every retrieved result, in every debug script you write from here on. It costs one line and it is what makes the debugging in Part 5 possible at all.

Where the source is thin

Three things this part inherits from the course as gaps rather than answers, stated plainly:

  • PyMuPDFLoader is recommended as the all-rounder and never used. No file in either repo

imports it. The best-on-all-fronts verdict 00:18:41 is the instructor's judgement, not a measurement shown on screen.

  • UnstructuredLoader / UnstructuredPDFLoader are described but never installed or run.

The unstructured dependency chain is heavy — system libraries for OCR and office formats — and none of that setup cost appears in the course. It is also, unhelpfully, the default loader_cls for DirectoryLoader.

  • WebBaseLoader and DirectoryLoader are slides plus unexecuted repo code. Nobody

watched them run. The bs_kwargs no-op above is the kind of defect that survives when code is written but never demoed; the sequential-versus-async fetching question had to be settled by reading the library rather than the course.

None of that invalidates the layer. It does mean that when you reach for anything beyond TextLoader and PyPDFLoader, you are past the point the source verified, and you should verify it yourself — with a len(documents) and a metadata dump, which is exactly the inspection ritual this chapter teaches.

Checklist

Environment:

  1. OpenAI key minted under Settings → API keys, scoped to a project; secret copied at

creation into your password manager.

  1. Anthropic key minted under platform.claude.com → Manage → API keys, scoped to a

workspace; secret copied at creation.

  1. uv init + uv venv + source .venv/bin/activate in a clean directory.
  2. `uv add langchain langchain-core langgraph langchain-openai langchain-anthropic

python-dotenv` — six packages, one command.

  1. .env created with OPENAI_API_KEY and ANTHROPIC_API_KEY; .env present in

.gitignore alongside .venv/, __pycache__/ and chroma_db/. (USER_AGENT goes in the shell environment, not .env — it is read at import time.)

  1. load_dotenv() is the first executable statement in every entrypoint, before any client is

constructed.

  1. Versions read via importlib.metadata.version("langchain-core"), never

from langchain_core import __version__.

  1. uv run main.py prints four things: two versions, an OpenAI response, an Anthropic

response, Setup complete!.

  1. Every model call uses .invoke(); you know the return is a message object and the text is

.content.

  1. You standardised on model= (never relying on the class default) and on temperature=0

for anything you want reproducible.

Loading:

  1. uv add langchain-community (loaders), uv add pypdf (PDF parsing), uv add bs4

(WebBaseLoader) — expect one missing parser per new format.

  1. Loader instantiation lives in exactly one factory function, so a swap is one line.
  2. Every ingest prints len(documents) and documents[0].metadata at least once, from your

own installed version, before you trust it.

  1. No code path does documents[0] on a PDF load.
  2. Citations render page_label; filters use page.
  3. source is normalised once at ingest (str(Path(p).resolve()) or a stable business id) —

never a raw tempfile name and never the literal string a caller happened to type.

  1. DirectoryLoader always gets an explicit loader_cls, an explicit recursive, and either

autodetect_encoding or silent_errors plus a skip count you actually log.

  1. Anything that depends on document order sorts the paths itself rather than trusting

lazy_load().

  1. Large ingests use .lazy_load(); multi-URL web ingests use .alazy_load() and set

requests_per_second, continue_on_failure and raise_for_status deliberately.

Decisions to make

DecisionDefaultChange it when
Package manageruv, exclusivelyNever, within this guide
Python floor>=3.12 (main repo); >=3.13 for the Parts 14–16 materialYour deploy target forces older — then check every pin
ProvidersOpenAI + AnthropicAny two you can actually call; the code is provider-agnostic by construction
Smoke-test modelgpt-4o-mini, temperature=0Never use a frontier model for plumbing checks
PDF loaderPyPDFLoaderHigh volume → PyMuPDFLoader; tables/layout → UnstructuredPDFLoader
load() vs lazy_load()load() while the corpus is smallCorpus stops fitting comfortably in RAM
Metadata schemasource (normalised) + page/page_label + whatever you will filter onDecide before the first ingest — changing it means re-embedding everything

Next: the documents you just loaded are still whole documents, and whole documents are not what you index. Part 3 splits them — and shows the measured A/B in which the theoretically better chunker loses 1–4.