RAG & Knowledge Systems Engineering · Module 03 of 18

Foundation

Documents, Parsing & Knowledge Sources

Learn how files become trustworthy knowledge objects with identity, text, metadata and parsing status.

Engineering focus: Turn files into usable evidence

In plain English

What problem are we solving?

Learn how files become trustworthy knowledge objects with identity, text, metadata and parsing status.

You are not expected to know the engineering vocabulary before using the idea. Formal terminology comes after the mental model.

Running case · Evidence Desk

Improve the same system, module by module.

Carry one evidence-grounded knowledge assistant through all 18 modules. Preserve source IDs, retrieval evidence, evaluation cases, authority decisions and security assumptions so every improvement is measurable.

Python bridge RAG glossary

Mental model

Understand it before you optimize it.

Treat every source like evidence in a case file: it needs identity, origin, version and integrity—not just extracted text.

01Source file

02Parse

03Normalize

04Attach metadata

05Checksum

06Knowledge record

Remember

Bad ingestion silently creates bad retrieval later.

Learning objectives

By the end of this module, you should be able to:

Model a document as content plus identity and metadata.
Explain why parsing quality affects retrieval quality.
Preserve provenance through ingestion.

Documents are not just strings

A useful knowledge object carries source ID, title, URI/path, timestamp, owner, access metadata and parser status alongside text.

Parsing is part of retrieval quality

Broken PDF extraction, lost headings or merged tables can make perfect embeddings useless because the searchable text no longer represents the source.

Provenance begins at ingestion

If source identity is lost during parsing, later citations cannot be defensible.

Untrusted content remains untrusted

Documents can contain malicious or misleading instructions. Retrieval should treat them as data, not policy authority.

Engineering depth

Engineering deep dive

Record source URI/path, source class, version/effective time, parser version and content checksum.
Treat parser failures and empty extractions as observable ingestion errors.
Keep raw-to-normalized lineage so a retrieved chunk can be traced to the original source.
Classify trust/authorization metadata at ingestion rather than inferring it during generation.

Worked examples

Mental model

Module 03: Turn files into usable evidence

Learn how files become trustworthy knowledge objects with identity, text, metadata and parsing status.

A knowledge record, not a string

{
  "source_id": "runbook-001",
  "version": "2026-10-01",
  "status": "active",
  "trust_zone": "internal-approved",
  "sha256": "...",
  "parser": "markdown-v2",
  "text": "..."
}

Identity and lifecycle metadata travel with text.
A checksum helps prove which bytes produced the record.

Diagnostic lens

If this goes wrong, where do you look first?

Symptom

A known document is present but cannot be found reliably.

Likely causes

Parser dropped text
Source identity was lost
Encoding or extraction failed

First checks

Compare raw file to normalized text
Inspect parser status
Verify source checksum and metadata

Engineering principle

Debug ingestion before changing search.

Try it · core lab · account-free

Lab 03 — Documents, Parsing & Knowledge Sources

Goal: Normalize Markdown and text files into JSON records with source IDs and checksums.

Before you start

Core lab requires only Python 3 and local files unless otherwise stated.
Running case: build the same evidence-grounded knowledge assistant across the course.
Keep source IDs and intermediate evidence so each result is inspectable.
Reflection: Write one sentence describing what this step proves and one sentence describing what it does not prove.

STEP 1

Run the baseline

python3 - <<'PY2'
from pathlib import Path
import hashlib,json,tempfile
p=Path('/tmp/rag-source.md'); p.write_text('# Runbook\nRestart only after health checks.\n')
text=p.read_text(); rec={'source_id':'runbook-001','path':str(p),'sha256':hashlib.sha256(text.encode()).hexdigest(),'text':text}
print(json.dumps(rec,indent=2))
PY2

STEP 2

Inspect the evidence

Record the intermediate source IDs, ranks, metadata or state produced by the baseline. Explain which pipeline layer this evidence belongs to.

STEP 3

Detect drift

After computing the checksum, change the source file and recompute it. Confirm the knowledge record can detect that the underlying bytes changed.

STEP 4

Diagnose and restore

Debug ingestion before changing search. State the failing layer, change only that layer, then repeat the verification checks.

STEP 5

Write the engineering note

Record: hypothesis → evidence → change → observed result → remaining limitation. Keep this note with the running Evidence Desk project.

Verify

Each document record has stable source identity and a content hash.
The text can be traced back to its source.
The baseline and the deliberately broken case produce different, explainable evidence.
You can name the pipeline layer that owns the failure and the control that repairs it.

Expected outcome

A reproducible local result plus a short evidence note.
A short before/after record showing the failure, diagnosis and repaired state.

Break / fix · diagnose

Inspect the intermediate evidence before changing the model or prompt.
If a command fails, preserve the error and classify which pipeline layer failed.
Change one pipeline variable at a time and rerun the same test case.
Do not accept a plausible answer as proof; verify the intermediate evidence and source identity.

Production view

Production RAG improves when every change can be traced to evidence at a specific pipeline layer. In production, retain the before/after evidence so the same failure can become a regression test.

Production checklist

What would an engineer verify before shipping this layer?

Gate 1

Source identity/version/checksum retained

Gate 2

Parser failures observable

Gate 3

Trust/authorization metadata assigned

Avoid these traps

Common beginner and engineering mistakes

Dropping filenames/URIs after parsing.
Ignoring parser errors.
Treating document text as trusted instructions.

Knowledge check

Can you explain the idea and diagnose the system?

1Why keep a document checksum?

To identify the exact content version used for indexing or evidence.

2What happens if parsing destroys headings?

Chunking and retrieval may lose important structure and relevance.

3Is retrieved document text trusted application policy?

No. It is untrusted evidence data.

4What is provenance at ingestion?

Preserving enough identity and metadata to trace a chunk back to its original source.

My Learning

Record your progress for this module.

Progress is saved in this browser immediately. When you sign in to My Learning, it can also sync across devices.

Not started

Core lab attemptedRecord this after meaningfully completing or attempting the module's core lab.Knowledge checks attemptedThis is marked automatically after you open every answer in the module; you can also record it manually.

Attempt the core lab and knowledge checks before marking the module complete.