GSA / GSA/MasteringAgenticAISystems_supplementals

[Lab]: Write a lab for Chapter 6.3C: ETL Practice for RAG Knowledge Bases (Incremental Updates, Semantic Chunking, Streaming Ingestion)

Open
#2 0 comments 0 reactions 0 assignees View on GitHub
effort:large help wanted track:labs
Dominant language
Python
Stars
40
Forks
16
Avg merge
16h 29m
Merged PRs (30d)
2

Description

(Do NOT add `good first issue` — a full lab is 8-20 hours of work and is not small/low-context, per the labs audit's guidance on reserving that label for genuinely small tasks.)

## Target chapter

**6.3C** — real topic pulled from the legacy file's own heading: "Chapter 6, Section 6.3.4-6.3.9: ETL Practice, Pitfalls, and Resources" (`labs/archive/Part_06_Chapter_6.3C_ETL_Practice.md`). The chapter covers building ETL pipelines that populate the vector databases RAG systems retrieve from: incremental/change-detection updates, domain-aware chunking that preserves code blocks and section boundaries, and production pitfalls (missing quality validation, naive chunking, full-refresh inefficiency).

## Knowledge items / exam skills covered

The `cert_mapping/nvidia_NCP-AAI.csv` row for chapter 6.3C rates NVIDIA knowledge-area column "6.3" as **H** (highly relevant), with "6.1", "6.2", "6.4", "6.5" at **M**. However, `nvidia_NCP-AAI.csv` has no accompanying `.md` legend describing what each numbered knowledge-area column actually means in prose (confirmed missing — `_cfc/workstreams.md` §3 notes this as an open completion gap), so this issue cannot state the exact H-rated knowledge-item phrase with confidence. **Contributor: before writing front matter, open `cert_mapping/nvidia_NCP-AAI.csv`'s "6.3" column header context (cross-reference against the NVIDIA exam guide PDF at `cert_mapping/nvt-study-guide-new-agentic-ai-cert-exam-4230000.pdf` if needed) to phrase the `knowledge_items` entries precisely, in the style of the worked example in `labs/README.md` §6** (e.g. `"8.2B: circuit breaker state machine..."`).

Based on the legacy file's evident subject matter, the lab should reinforce at minimum:
- Three-stage ETL architecture (extract/transform/load) and why the stages stay separated
- Incremental update / change-detection design (state tracking, `WHERE updated_at > last_run` patterns) versus full-refresh
- Domain-aware chunking that respects semantic boundaries (code blocks, section headings) over fixed-size splitting
- Data-quality validation as a control point before vector-DB loading

## Prerequisites

- Python 3.10+ and comfort with classes, exceptions, and `dataclasses`
- A local vector store the learner can run without cloud credentials (e.g. an embedded/local Milvus Lite, Chroma, or FAISS instance — pick one and pin it in `requirements.txt`; the legacy file's own examples assume a full Milvus deployment, which is heavier than a lab needs)
- Basic SQL familiarity (the incremental-update exercise queries a database with a parameterized `WHERE` clause)
- No prior lab required, though 6.1A (RAG fundamentals) is a natural predecessor if it exists by the time this is picked up

## Reusable content from an existing example file

- [x] I've identified an existing `labs/` file with reusable scenario/code content for this chapter.

**Existing file to salvage from:** `labs/archive/Part_06_Chapter_6.3C_ETL_Practice.md`

Per `labs/README.md` §5, this is "clean mapping; richest legacy file in the set" for chapter 6.3C, confirmed by reading it directly.

**Quoted excerpt** (from `labs/archive/Part_06_Chapter_6.3C_ETL_Practice.md`, section "6.3.5 'You Do' - Independent Practice", subsection "Challenge: Real-Time ETL Pipeline for Support Tickets"):

> "Your task is building a streaming ETL pipeline that monitors the Zendesk API for new support tickets, extracts ticket content including comments and metadata, transforms and chunks the ticket data for optimal retrieval, and loads it into a vector database in real-time. The target is aggressive: tickets must become searchable within 30 seconds of creation.
>
> ...you must handle API rate limits gracefully—Zendesk allows 100 requests per minute, and exceeding this results in temporary blocking. ... Processing 1,000+ tickets daily means roughly one new ticket every 90 seconds on average, though real traffic shows bursts during business hours. The API rate limit of 100 requests per minute translates to one request every 600 milliseconds maximum—stay below this threshold consistently."

**What to do with it:** Reuse this scenario's framing (a support-ticket knowledge base needing near-real-time searchability, with a concrete rate limit and freshness SLA) as the lab's Scenario section — it is exactly the kind of realistic, numeric practitioner situation `labs/LAB_TEMPLATE.md` asks for. Do not copy the accompanying `StreamingTicketETL` skeleton code as-is: it has no pinned dependencies, is an unfinished skeleton with `pass` bodies (not independently runnable), and assumes a live Zendesk account the learner won't have. Rewrite the You Do task from scratch against the template using a mocked/simulated ticket source (e.g. a local JSON fixture or a `unittest.mock`-backed fake API) so `starter.py` runs and is gradable without external credentials, while keeping the rate-limit and dedup numbers above as the concrete constraints the learner's implementation must satisfy.

A second salvageable fragment, from "6.3.4 'We Do' - Guided Practice", Guided Exercise 1: the `ETLStateManager.get_last_run`/`save_run_state` cold-start pattern (defaulting to a 24-hour lookback window when no state file exists) is a reusable *design idea* for the We Do section's guided walkthrough — but, per the same caution, write the actual `starter.py`/`solution.py` code fresh rather than copying the legacy file's inline snippet verbatim.

## Estimated time for the learner

**1-2 hours** (author's estimate — to be refined once the lab exists and gets piloted; this is an ETL/pipeline lab with a guided section plus an independent streaming-ETL challenge, more involved than the 60-90 minute reference lab at 8.2B).

## Definition of done

- [ ] Cites specific knowledge items — front matter names one or more specific chapter 6.3C knowledge items (chapter ID + phrase), not just the chapter number (see note above on confirming exact phrasing against `cert_mapping/*.csv`)
- [ ] The learner does the work — the "You Do" section requires the learner to write or complete real code (e.g. the incremental-update state manager or the domain-aware chunker) themselves, not read a walkthrough
- [ ] Stands alone — comprehensible and completable without the book chapter open; necessary context restated in Scenario/Setup
- [ ] Starter code runs as given — `starter.py` installs and executes without errors before any learner changes (may fail its own tests, must not crash on import/setup)
- [ ] Solution runs, dependencies pinned — `solution.py` passes `test_lab.py`, and `requirements.txt` pins exact versions matching `frameworks` front matter
- [ ] Learner-verifiable success — a concrete, learner-executed check (test suite or script) yields an unambiguous pass/fail signal
- [ ] Realistic scenario — framed around a plausible practitioner situation (a named system, a real failure mode/requirement), not an arbitrary toy
- [ ] Lab reaches at least `draft` maturity per `labs/README.md`'s maturity ladder (written against `LAB_TEMPLATE.md`, passes the rubric on inspection, author has run the solution and confirmed its tests pass)

## Estimated effort (to write)

**~12-20 hours.** This chapter needs an external service dependency (a vector store) even in its lightest form, per `_cfc/workstreams.md` §1's effort bands — most of the setup/debugging time goes into making a local vector-store environment reliably reproducible for a stranger, not into the exercise logic itself. This matches the Tier 1 sequencing note in `_cfc/workstreams.md` §1 identifying 6.3C/6.5B as "RAG/data-pipeline, needs one external service."

## Required skills

Python, SQLAlchemy or equivalent for the incremental-update database query, comfort with a local/embedded vector store (Chroma, FAISS, or Milvus Lite), regex for the chunking exercise, and the ability to write a deterministic `unittest`-based (or `pytest`-based, if `requirements.txt` already needs pytest) self-check.

## Exemplar to follow

- [`labs/8.2B_circuit_breaker/lab.md`](https://github.com/GSA/MasteringAgenticAISystems_supplementals/blob/master/labs/8.2B_circuit_breaker/lab.md) — the reference lab this repo's labs are modeled on (maintainer-verified `draft`, zero third-party dependencies, full hint ladder, citation table)
- [`labs/LAB_TEMPLATE.md`](https://github.com/GSA/MasteringAgenticAISystems_supplementals/blob/master/labs/LAB_TEMPLATE.md) — the fill-in skeleton to copy for structure

## Additional notes

A maintainer will comment to confirm this chapter/topic isn't already claimed before you start writing. Keep each pull request to roughly 20 changed items or fewer — see `_cfc/workstreams.md` §5 for how to split an oversized lab PR into scaffolding / guided section / independent section+solution / polish, each independently mergeable.

## Where to ask questions

See [SUPPORT.md](https://github.com/GSA/MasteringAgenticAISystems_supplementals/blob/master/SUPPORT.md) — GitHub Issues is the primary channel; expect a first response within 3 business days.

Contributor guide

Open the contributing guide

Research direction

Start with labs/LAB_TEMPLATE.md and labs/README.md §5-6, then inspect labs/archive/Part_06_Chapter_6.3C_ETL_Practice.md and the 6.3C row and header context in cert_mapping/nvidia_NCP-AAI.csv. Use labs/8.2B_circuit_breaker/lab.md as the structural exemplar. Done means a standalone lab with pinned dependencies, runnable starter and solution, passing test_lab.py, precise knowledge-item citations, and verified draft maturity.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, sql, sqlalchemy
Domain
data-engineering, databases, machine-learning
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.