Amateurfunk-Anki/CLAUDE.md

Amateurfunk — BNetzA Question Catalog → Anki Decks

A small two-stage Python pipeline that downloads the German amateur-radio exam question catalog ("Fragenkatalog") published by the Bundesnetzagentur (BNetzA) and turns it into Anki decks.

The full source-discovery notes, JSON schema, exam-structure details, and per-stage design decisions live in DESIGN.md. This file is a short orientation for anyone (human or agent) opening the project.

What the catalog is

• Official German amateur-radio exam questions for classes N, E, A (German license tiers).
• Published by the Bundesnetzagentur under the DL-DE→BY-2.0 open data license (free reuse, attribution required).
• Distributed as a single ZIP containing one JSON file with the full question tree, plus a svgs/ folder with figures referenced by individual questions.
• Current edition at time of writing: 3. Auflage, März 2024 (issued 2024-03-20, valid from 2024-06-24, ~1750 questions).

Canonical source

• ZIP (machine-readable): https://www.bundesnetzagentur.de/SharedDocs/Downloads/DE/Sachgebiete/Telekommunikation/Unternehmen_Institutionen/Frequenzen/Amateurfunk/Fragenkatalog/PruefungsfragenZIP.zip?__blob=publicationFile
• Landing page (short link): https://www.bnetza.de/amateurfunk-fragenkatalog
• PDF (human-readable, not used by this pipeline): same path with Pruefungsfragen.pdf instead of PruefungsfragenZIP.zip.

The ZIP URL is stable across editions — BNetzA replaces the file in-place. The Last-Modified HTTP header is reliable for change detection. The filename inside the ZIP (fragenkatalog3b.json) encodes the edition (3b = 3rd edition, revision b) and will change on new editions, so we discover it from the archive rather than hard-coding.

Pipeline overview

BNetzA ZIP ──[Stage 1: amateurfunk_fetch.py]──► data/<slug>/
                                                  ├── fragenkatalog*.json
                                                  ├── svgs/
                                                  ├── README.txt
                                                  └── manifest.json

data/ ──[Stage 2: amateurfunk_anki.py]──► anki/
                                            ├── amateurfunk-technische-kenntnisse-n.apkg
                                            ├── amateurfunk-technische-kenntnisse-e.apkg
                                            ├── amateurfunk-technische-kenntnisse-a.apkg
                                            ├── amateurfunk-betriebliche-kenntnisse.apkg
                                            └── amateurfunk-kenntnisse-von-vorschriften.apkg

Stage 1 — amateurfunk_fetch.py

1. Download the ZIP from the canonical URL.
2. Verify it is a valid ZIP and contains the expected JSON + SVG files.
3. Extract to a target directory (default: ./data/<edition>/).
4. Emit a small manifest.json next to the data: source URL, fetched-at timestamp, Last-Modified from the server, JSON edition metadata, sha256 of the ZIP.
5. Be idempotent — re-running without an upstream change is a no-op. The skip key is the HTTP Last-Modified header recorded on the previous manifest; the ZIP is deleted by default after extraction, so the recorded sha256 is provenance, not a re-verification target. See DESIGN.md §4 for the full idempotency contract.

Stage 2 — amateurfunk_anki.py

1. Read the latest edition from data/ (following manifest-latest.json to a per-edition directory).
2. Split the catalog into five categories. Betriebliche and Vorschriften get one deck each (shared across every candidate). Technische is additionally fanned out per license class into three decks (N / E / A) using a strict equality split on the question's class field. The klasse-N|E|A tag is still emitted on every note for inside-Anki filtering.
3. Render every question as an Anki note: shuffled A/B/C/D choices on the front, the displayed position of the correct answer on the back. Inline $...$ LaTeX is converted to MathJax \(...\) delimiters; the catalog's safe inline markup (<u>...</u>) is preserved. If the question's number has an entry in explanations.json (see EXPLANATIONS.md), an English explanation block is appended to the back; a "low confidence" badge shows for entries with confidence < 7.
4. Hand-roll the v11 Anki collection (SQLite + JSON config) and package it as a .apkg ZIP with deterministic timestamps. By default each build mints a fresh shuffle seed, so answers are reshuffled every run. Pass --seed (and --epoch) for the reproducible-build contract: same catalog + same seed + same timestamp → byte-identical output across runs.

The Anki design decisions (shuffle seeding, deterministic build epoch, SVG dark-mode handling, schema choices) live in DESIGN.md §7.

Repo conventions

• Python 3.11+, standard library only. No third-party dependencies in either stage.
• Single-file scripts: amateurfunk_fetch.py, amateurfunk_anki.py. No frameworks, no CLI library beyond argparse.
• Style: section banners, commented constants, docstrings on every function, inline comments at decision points. The two scripts intentionally read the same way.
• Outputs are build artifacts: kept under data/ and anki/, both gitignored.
• License attribution string (required by DL-DE→BY-2.0) is preserved verbatim from the upstream README.txt whenever we redistribute the data.

Working on this repo

• EXPLANATIONS.md — the editorial contract for agents asked to add or improve per-question explanations. The schema, the workflows ("explain everything unexplained", "improve everything below confidence 7"), and the source/confidence guidance live there. explanations.json is an empty {} until agents populate it.
• Start from DESIGN.md — it has the JSON schema, the question/answer conventions (answer A is always correct upstream → consumers shuffle before display), the LaTeX-in-questions caveat, the exam-structure rationale for the Anki package layout (Betriebliche, Vorschriften, and Technische split per license class), and per-stage design notes.
• Do not invent new download URLs; the ones in DESIGN.md were verified against the live BNetzA site.
• When BNetzA publishes a new edition, expect a new fragenkatalog<N><rev>.json filename inside the ZIP. The fetcher must not hard-code the current name.
• Both stages have a fixture-driven test suite. Run with python3 -m unittest test_amateurfunk_fetch test_amateurfunk_anki. Network access is only needed for the manual smoke test of Stage 1.