# 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  (one file, 11 topic sub-decks)
                                            ├── amateurfunk-technische-kenntnisse-a.apkg  (one file, 11 topic sub-decks)
                                            ├── amateurfunk-betriebliche-kenntnisse.apkg
                                            └── amateurfunk-kenntnisse-von-vorschriften.apkg

shorthand.json ──[Stage 2b: amateurfunk_shorthand.py]──► anki/
                                            └── amateurfunk-abkuerzungen-q-gruppen.apkg

technical.json ──[Stage 2c: amateurfunk_technical.py]──► anki/
                                            └── amateurfunk-technische-abkuerzungen.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 using a
   strict equality split on the question's `class` field: one `.apkg`
   each for N, E, and A. The E (463) and A (716) packages — the large
   pools — are each built as a deck *tree*: one sub-deck per
   first-level catalog topic (the 11 subsections) under an anchoring
   `Technische Kenntnisse::E` / `::A` parent, so each imports as a
   single file but studies topic by topic. N stays a single flat deck.
   The set of split classes is `TOPIC_SPLIT_CLASSES`. 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.

### Stage 2b — `amateurfunk_shorthand.py`

A sibling builder for a standalone reference deck of Q-groups and
operating abbreviations — the ones in the exam plus the most common
on-air shorthand the exam never covers (real operating knowledge, not
just the test). Content lives in the hand-curated `shorthand.json`
(editorial, tracked in git, like `explanations.json`); the
`references/Q-Codes.md` reference is where the exam-present codes were
catalogued.

Each code is one Anki *note* with two card templates — forward
(code → meaning) and reverse (meaning → code) — so a single record
drives both directions. A Q-group means one thing as a statement
(`QSO`) and another as a question (`QSO?`), so each Q-group yields two
notes; plain abbreviations yield one. All IDs/GUIDs are hashed from the
displayed code form (stable re-import). The deck is catalog-independent
and fully deterministic; it only consults `data/` to borrow the
manifest build epoch when present. Low-level apkg/SQLite machinery is
imported from `amateurfunk_anki.py` so the two stay in lockstep. The
glossary machinery shared with Stage 2c (two-template note type,
two-cards-per-note writer, packager, build-epoch resolver, entry
validator) also lives here.

### Stage 2c — `amateurfunk_technical.py`

A third glossary deck, same card mechanics as Stage 2b (one note,
forward+reverse templates), for the *technical* vocabulary rather than
operating shorthand: modulation/modes (SSB, FM, CW), signal domains
(NF, HF, ZF), building blocks (VFO, PLL, AGC), components, measurements
(dB, SWR, PEP), propagation, digital modes, and the
organisations/regulations (ITU, CEPT, EMV) — exam terms plus common HAM
abbreviations beyond the exam. Content lives in the curated
`technical.json`; each entry carries a German `category` (Betriebsart,
Bauteil, …) shown on the card and used as a `kategorie-*` tag. The
shared glossary machinery is imported from `amateurfunk_shorthand.py`;
this script only adds the data shape, the deck/model names, and the tag
scheme. IDs live in their own `technical` namespace so the two glossary
decks never collide on import.

## 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"), the source/confidence guidance, and the **MathJax
  typesetting rules (§4a) with a verification sweep** live there. The
  `$...$` typesetting is the most error-prone part of the file — read
  §4a before touching any formula, and fix every occurrence in both the
  explanation body and the `Hilfsmittel:` note.
- 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.