The Problem

Learners need a self‑contained, reproducible environment to run the hands‑on notebooks and quizzes that accompany the Hugging Face Agents Course. Without clear build instructions or a locked dependency set, reproducing the small Python utilities (quiz loader, translation scripts) can be fragile for students or CI pipelines.

What This Does

The repository is primarily a documentation bundle. All instructional content lives under units/ as .mdx files (≈ 420 files) and is language‑agnostic. The only executable parts are:

  • quiz/push_questions.py – reads quiz/data/unit_1.json and pushes the questions to the HF Agents‑Course backend.
  • scripts/translation.py – processes the markdown translation agreements in translation_agreements/.
  • scripts/vi.py – a small helper used by the translation workflow (exact purpose is defined in the script header).

Dependency metadata lives in quiz/pyproject.toml (with a matching quiz/uv.lock). The CI definition (.github/workflows/*.yml) builds the documentation but does not run the Python utilities.

How It Is Wired

Entry point → quiz/push_questions.py

  1. Execution starts when the user runs python -m quiz.push_questions (or uv run push_questions.py).
  2. The script imports json and opens quiz/data/unit_1.json.
  3. It iterates over the JSON payload, constructing HTTP POST requests to the course API (URL hard‑coded in the script).
  4. Network I/O is performed via requests (declared in pyproject.toml).
  5. No further internal calls; the script exits after the last POST succeeds.

Entry point → scripts/translation.py

  1. Run with python scripts/translation.py.
  2. The script walks translation_agreements/ looking for *.md files.
  3. For each file it parses the markdown front‑matter (via yaml), extracts the language mapping, and writes a normalized JSON file to scripts/_generated/ (folder created at runtime).
  4. Calls back to scripts/vi.py only if a “visual‑inspect” flag is present in the front‑matter; otherwise it finishes.

Dependency graph

  • quiz/push_questions.py → requests, json (standard lib).
  • scripts/translation.py → yaml, pathlib, scripts/vi.py.
  • scripts/vi.py → only standard‑library utilities.

The rest of the repo (units/, .github/, README.md) has no runtime impact. No circular imports are present; the Python code forms two tiny, independent trees. The widest blast radius is the push_questions.py network call – a failure there prevents quiz publishing but does not affect the documentation build.

How To Use It

# 1. Clone the repo (use the URL verbatim)
git clone https://github.com/moses-y/agents-course
cd agents-course

# 2. Install Python tooling (requires Python ≥3.10)
# The repo ships a .python-version file; uv respects it.
uv sync --frozen   # respects quiz/uv.lock; installs requests, pyyaml, etc.

# 3. Run the quiz uploader (requires HF API token in env)
export HF_API_TOKEN=YOUR_TOKEN
python -m quiz.push_questions   # or: uv run quiz/push_questions.py

# 4. (Optional) Generate translation artefacts
python scripts/translation.py

Configuration: The only required runtime secret is HF_API_TOKEN, read directly from the environment in push_questions.py. No additional config files are referenced.

Documentation build: The CI workflow build_documentation.yml runs mkdocs build (implicit from the repo’s mkdocs.yml, not listed here). To build locally:

pip install mkdocs mkdocs-material
mkdocs build

Real‑World Use

A university’s data‑science lab could clone the repo, install the pinned dependencies with uv sync, and run push_questions.py as part of a weekly CI job that refreshes the course quiz content on the Hugging Face platform. The translation script can be invoked to keep multilingual markdown in sync before each release.

Code Health & Issues

  • Low – Dependencies declared without a lockfile – quiz/pyproject.toml (the repo does include quiz/uv.lock, but the CI does not reference it).
  • Low – No automated tests for the Python utilities – test files exist (7 total) but none target push_questions.py or translation.py.
  • Low – CI only builds documentation; it never exercises the Python scripts, so regressions in those utilities would go unnoticed.

No security‑critical secrets are committed, and the license (LICENSE) is present.

The Bottom Line

The repo delivers a rich, multilingual tutorial set, but the runnable components are minimal and lack a defined test suite or CI verification. It is suitable for educators who need the course material and a simple way to publish quiz data, provided they add their own validation steps for the Python helpers.