methods-harness

Pipeline-engineering harness for VCE Mathematical Methods 3-4: SymPy verification · bilingual lesson PDFs · cheat sheets · mock SAC papers — all reproducible from one CLI.

Why

Hand-writing VCE study materials is slow and error-prone:

• Math is easy to typo (a wrong sign in a derivative breaks every downstream example).
• Bilingual (EN + 中文) explanations need every formula re-verified twice.
• One curriculum revision means re-rendering 12 PDFs by hand.

methods-harness treats lesson production as a pipeline: SymPy verifies every formula → Markdown lessons inject placeholders → KaTeX/MathJax renders inline math → headless Edge / Chromium prints PDFs → validators sweep the outputs before they ship. The same harness produces lesson notes, cheat sheets, mock SACs, and diagrams.

How

                 ┌──────────────────┐
                 │  harness.py      │   SymPy backend
                 │  (functions)     │   • derivative / integral
                 └────────┬─────────┘   • factor / solve / transform
                          │             • coordinate geometry
                          ▼
            ┌─────────────────────────┐
            │  validators/ (5)        │   answer correctness
            │  agents/    (2)         │   CAS simulator + SAC audit
            └────────────┬────────────┘
                         │
                         ▼
        ┌───────────────────────────────────┐
        │  lessons/   →  make_pdf.py        │   markdown → KaTeX → PDF
        │  cheat_sheet.md → make_cheat_pdf  │   bilingual cheatsheet
        │  mock_sac/  →  paper + solutions  │   exam-style PDF
        │  diagrams/ →  matplotlib PNG      │   transformation visuals
        └───────────────────────────────────┘

Architecture follows the harness-engineering pattern (agents + validators + manifest), adapted for a single-author EdTech use case.

Numbers

• 5 validators (derivative / integral / poly_factor / transform / trig_solve) using SymPy
• 2 agents (CAS simulator, SAC paper auditor)
• 5 chapter lessons covering Cambridge Methods Ch 1–10 + VCAA AoS 1–3
• 15 diagrams (unit circle, transformations, discriminant cases, …)
• 1 mock SAC with paper + solutions PDFs
• 62 / 62 PASS SymPy claim-checks on the Ch1–3 lesson run that produced the 1.86 MB bilingual PDF (separate from the 21-case pytest suite in the badge above)
• ~4 200 lines of Python (SymPy + Jinja2 + matplotlib)

Quick start

# 1) Clone & install
git clone https://github.com/lfzds4399-cpu/methods-harness.git
cd methods-harness
python -m pip install -e .[dev,pdf]

# 2) Health check
python cli.py doctor

# 3) Render lessons
python cli.py run --chapter 1-3        # one chapter range
python cli.py run --chapter all -q     # all chapters, quiet mode

# 4) Audit outputs
python cli.py audit
python cli.py status                   # see manifest

Repository layout

methods_harness/
├── harness.py              SymPy backend (derivative/integral/transform/…)
├── cli.py                  typer CLI: status / doctor / run / audit
├── logging_setup.py        quiet-mode aware logging
├── manifest.py             stage state persistence (data/manifest.json)
├── lessons/                5 chapter Markdown files (197 KB total)
├── validators/             5 SymPy correctness checks
├── agents/                 CAS simulator + SAC auditor
├── cheat_harness/          knowledge / render / scope validators
├── mock_sac/               mock paper + solutions
├── diagrams/               15 PNG visuals
└── data/, logs/            runtime state (gitignored)

Engineering principles

This harness follows three rules from the harness-engineering pattern:

1. Validators are mandatory — every lesson PDF runs through 5 SymPy validators before it ships, because typos in a derivative are invisible until a student gets the wrong answer.
2. Logs are split by audience — quiet mode keeps the console clean (works inside Claude Code) while still writing every detail to logs/pipeline_<ts>.log.
3. Manifest is the source of truth — every stage writes its status to data/manifest.json, so re-running is idempotent and partial failures are visible.

Limitations

• VCAA Mathematics Study Design 2023-2027 PDF is not redistributed (copyright VCAA). The harness reads it locally if present but the file is gitignored.
• Some chapter PDFs are large (>5 MB); only chapter-level demos are kept in git, full builds are gitignored.
• HTML→PDF requires headless Chrome / Chromium / Edge installed locally.

Credits

Built by Lin Feng (@lfzds4399-cpu) — software engineer based in Melbourne, AU. Operating under ABN 70 767 210 027.

Pair-programmed with Claude Code (Anthropic). Every commit message that involves significant AI assistance carries a Co-Authored-By: Claude trailer for transparency.

License

MIT — see LICENSE.