imple/Amateurfunk-Anki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add explanations

Browse Source
This commit is contained in:
Renat Nurgaliyev
2026-05-22 16:17:05 +02:00
parent 0d635a8587
commit 27988780cf
7 changed files with 933 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
EXPLANATIONS.md
+425
View File
@@ -0,0 +1,425 @@
# Explanations — agent-authored answer rationales
This document is the working contract for any AI agent (or human)
asked to **add or improve explanations** for questions in the BNetzA
amateur-radio catalog. The decks built by `amateurfunk_anki.py`
optionally append an English explanation block to the back of each
card; the text of those explanations lives in `explanations.json` at
the repo root and is edited by hand (or by an agent following this
file).
The build is non-blocking on this data: a missing file or missing
entry just produces a card without an explanation block. Adding an
entry is purely additive — no regenerate ceremony beyond
`make anki`.
---
## 1. File location and shape
- **Path:** `explanations.json` at the repo root. Tracked in git.
- **Encoding:** UTF-8, no BOM, two-space indent for readability.
- **Top level:** a JSON object keyed by **question number** exactly
as it appears in the catalog (e.g. `"NA101"`, `"BA205"`,
`"EH410"`). Keys are case-sensitive.
- **Sort order:** keep keys in alphabetical order. Diffs stay clean
and merge conflicts get easier; the build does not care.
### Per-entry schema
Every entry MUST have exactly these four fields:
| Field | Type | Constraint |
|---------------|---------|--------------------------------------------|
| `revision` | integer | `>= 1`. Starts at `1`, bumps on improvement |
| `explanation` | string | Non-empty. **English.** Terse. WHY-focused |
| `source` | string | Non-empty. URL or citation like `AFuV §16(2)` |
| `confidence` | integer | `1..10` inclusive. See scale in §5 |
Extra keys are rejected by `load_explanations()` — the build fails
with `unknown fields [...]` listing them. The loader is similarly
strict about types: a JSON `true` will not satisfy the integer
contract for `revision` or `confidence`. If you need to track
editorial metadata that isn't shown on the card, propose a schema
change rather than smuggling fields in.
Top-level keys (the question numbers) must also match the catalog
exactly. An entry keyed on a number that no live question carries
(typo, stale ID after a catalog revision) fails the build with
`explanation keys not present in the catalog: ...`. Fix the key, or
remove the entry.
### Minimal example
```json
{
"NA101": {
"revision": 1,
"explanation": "100 m weighs 210 g, so 55 g is 55/210 of 100 m ≈ 26.2 m. Mass scales linearly with length for the same wire.",
"source": "https://50ohm.de/lernen/wissen/elektrotechnik-mathematik",
"confidence": 8
}
}
```
The build appends this on the back card as a styled block headed
**Explanation**, with the source rendered as a clickable link when
it looks like an HTTP(S) URL.
---
## 2. How the explanation reaches the card
`amateurfunk_anki.py` does the wiring; the agent does not need to
modify Python code to ship a new explanation. End-to-end:
1. `load_explanations(./explanations.json)` parses the file and
validates each entry against the schema above. A malformed entry
is a hard build error.
2. While rendering a card, `render_question()` looks up the
question's `number` in the dict. On a hit, `render_explanation()`
produces an HTML block: header "Explanation", the body (with
inline `$...$` LaTeX rewritten to MathJax `\(...\)`, same as the
question text), and a "Source: ..." line.
3. The block lands inside `.af-back` at the very end, styled by the
`.af-explanation*` CSS rules — serif italic body, sans-serif
metadata, separated from the answer by a top border. When the
entry's `confidence` is **below 7**, a small "low confidence"
badge appears next to the **Explanation** header — a hint to the
learner that the reasoning may be incomplete or weakly sourced.
`revision` is never shown on the card.
4. The note GUID is keyed on `category.slug:number`, NOT on field
content, so adding/changing an explanation does **not** create
duplicate cards on re-import — Anki updates the existing note in
place.
Run `make anki` (or `python3 amateurfunk_anki.py`) after editing the
file. The CLI summary line will show `... N with explanations` per
deck.
---
## 3. Locating a question to explain
Questions live in the JSON catalog under the per-edition data
directory:
```
data/<slug>/fragenkatalog<edition>.json
```
To find one by number, e.g. `EH410`:
```sh
python3 -c '
import json, glob
for path in glob.glob("data/*/fragenkatalog*.json"):
cat = json.load(open(path))
def walk(node, prefix=()):
for q in node.get("questions", []) or []:
if q["number"] == "EH410":
print(json.dumps(q, ensure_ascii=False, indent=2))
print(" / ".join(prefix))
for s in node.get("sections", []) or []:
walk(s, prefix + (s.get("title", "?"),))
walk(cat)
'
```
You get the question stem, the four answers (`answer_a` is the
**correct** one upstream; the deck shuffles before display), the
class digit (`"1"` = N, `"2"` = E, `"3"` = A), and the section path.
That path tells you the topic context — useful when choosing a
source citation.
---
## 4. Writing the explanation
### Style
- **Language: English.** The questions and answers stay in German
on the card; the explanation is the one English element. Don't
switch.
- **Terse.** Aim for 1–3 sentences. The card already shows the
question, the correct answer text, and the breadcrumb — the
explanation should add the missing *why*, not restate any of
those.
- **Lead with the reasoning.** Don't open with "The correct answer
is X because..." — the card already declares the correct answer
one line above. Go straight to the principle, the formula, the
rule of thumb.
- **Math.** Use inline `$...$`; it's rewritten to MathJax on the
card, same as for question text. Don't use display math `$$...$$`
(the deck has no MathJax support for those).
- **Inline emphasis.** `<u>...</u>` is the only HTML you should
type by hand. Everything else gets HTML-escaped.
- **No spoilers about other answers.** If a distractor is a common
trap, naming the trap is fine; quoting the distractor's text is
noise.
### What "WHY-focused" means in practice
| Less useful | More useful |
|----------------------------------------------|-----------------------------------------------|
| "The correct answer is 26.2 m." | "55 g is 55/210 of 100 m by mass scaling." |
| "Because regulations require it." | "AFuV §16(2): only class A may operate ≤10 m." |
| "It's how the formula works." | "Q is reactance over resistance, so Q rises as R falls." |
If the *only* honest explanation is "memorize the table" (e.g. a
band-plan lookup), say that plainly and cite the band plan in
`source` — confidence stays low (3–4) until someone finds a deeper
hook.
---
## 5. Confidence scale
| Score | Meaning |
|------:|------------------------------------------------------------------------|
| 10 | Direct quote / arithmetic restatement from a primary legal source. |
| 8–9 | Derivation from a well-known formula or law text; no ambiguity. |
| 6–7 | Reasoning sound but condensed; a reviewer might want one more line. |
| 4–5 | Educated guess based on context; corroborating source is weak. |
| 1–3 | Best-effort placeholder. Flag for re-explanation. |
When in doubt, score lower. The query "explain everything below
confidence 7" is a real workflow — a too-generous score hides work
that should be redone.
The score is also capped by the source tier — see §6 "Source ↔
confidence linkage". A tier-8 (general web) source caps confidence
at 5 regardless of how persuasive the prose is.
**Card surface.** Confidence below 7 also surfaces a "low
confidence" badge on the card itself (see §2). This is deliberate:
the learner sees that the explanation is provisional rather than
trusting it as definitive. Scoring 7 turns the badge off, so do
not nudge a 6 to a 7 just to clear the badge — fix the explanation
or the source first.
---
## 6. Sources
Use the **strictest tier that actually answers the question**. Drop
down a tier only when the higher one doesn't cover the topic — never
because a lower-tier source is easier to find. The exam tests
knowledge of German law and BNetzA-curated material; a primary-law
question backed by a random tutorial site is a worse explanation
than no explanation at all.
The full priority order, top (most preferred) to bottom:
1. **Primary German law.**
- AFuG (Amateurfunkgesetz), AFuV (Amateurfunkverordnung), BEMFV,
TKG when applicable, plus frequency-allocation ordinances
(vfg / VVnömL).
- Canonical URL pattern: `https://www.gesetze-im-internet.de/<gesetz>/__<§>.html`.
Cite as `AFuV §16(2)` style. Use the URL form when possible so
the card link is clickable.
- If a question's answer is fixed by German law, **no lower tier
is acceptable** as the sole source.
2. **EU / international regulation binding on Germany.**
- CEPT recommendations (T/R 61-01, T/R 61-02), ITU Radio
Regulations, ECC decisions, EU EMC / RED directives.
- Use `docdb.cept.org/...` or the ITU document portal as the
canonical URL.
- Reach for this tier when the question references CEPT
licensing, foreign operation, or harmonised band plans that
AFuV doesn't restate.
3. **BNetzA official publications.**
- The question catalog's own `README.txt`, BNetzA "Vfg"
announcements, the German band plan as published by BNetzA,
official explanatory notes.
- Useful when primary law is too terse to convey the *why* on
its own — these are the regulator's own gloss on the law.
4. **German amateur-radio organisations.**
- DARC publications and band plan (`darc.de`), Runder Tisch
Amateurfunk (RTA) papers, **50ohm.de** (the community study
site linked from `README.md`).
- Exam-aligned by community convention; well-suited to the WHY
when law text alone isn't pedagogically clear.
5. **International amateur-radio organisations.**
- IARU Region 1 documents (Germany is in R1) and DARC's IARU R1
liaison material; ARRL publications when they explain the
underlying physics or an internationally harmonised band plan.
- ARRL is **not** a source for German licensing rules — don't
use it that way.
6. **Standards bodies and primary technical references.**
- NIST, IEEE, IEC, ITU-R recommendations, ETSI standards (when
not already binding via tier 2).
- Appropriate for purely technical questions — units, defining
equations, definitions — where no amateur-radio-specific
source applies.
7. **Established engineering references.**
- University lecture notes hosted by the university, recognised
EE textbook publishers, well-known authors' personal sites.
- Use only when tiers 1–6 don't cover the topic.
8. **General web technical sites — last resort.**
- Wikipedia, tutorial sites (`allaboutcircuits.com`,
`amateur-radio-wiki.net`, `biopac.com`, etc.), random
manufacturer pages, blog posts.
- **Treat citations at this tier as temporary.** Score
`confidence` ≤ 5 and consider the entry a §8.3 candidate for
re-sourcing the moment a higher-tier source is identified.
Never use a tier-8 source as the sole citation for a question
that has a clear answer in tiers 1–4.
### Source ↔ confidence linkage
The §5 confidence scale isn't independent of the tier:
- Tier 1–2 + sound derivation → 9–10 is appropriate.
- Tier 3–4 → cap at 8 unless the source quotes a primary citation.
- Tier 5–6 → cap at 7.
- Tier 7 → cap at 6.
- Tier 8 (sole source) → cap at 5. Flag for re-sourcing.
This isn't a hard limit the validator enforces — it's editorial
discipline. If you find yourself wanting confidence 9 with a
tier-7 source, you almost always either (a) need to find the
tier-1–4 source that backs the same claim, or (b) are about to
overstate certainty.
### Form
If the source is a URL, store it as one — `_source_html()` makes
plain `http://` / `https://` strings clickable. Mixed text+URL
sources are stored verbatim and rendered as escaped text (no auto
link), so prefer one or the other. A short citation like
`AFuV §16(2), gesetze-im-internet.de/afuv_2005/__16.html` is
acceptable but loses click-through. When possible, narrow the
source to a single canonical URL.
---
## 7. Revisions
`revision` is editorial bookkeeping; it never appears on the card.
- A brand-new entry starts at `revision: 1`.
- **Bump** when you materially improve the explanation, broaden the
source, or fix an error. A typo fix is not a revision bump.
- Don't lower the revision. If a previous revision was wrong, fix
it forward and explain the fix in the commit message.
- A revision bump usually pairs with a confidence bump (or, more
rarely, with a deliberate confidence reset to indicate the
reviewer is less sure than the prior author was).
---
## 8. Workflows
These are the common ways the file gets edited. The agent should
read the request and pick one.
### 8.1 "Explain question X"
1. Look up X in the catalog (§3) — read the stem, the correct
answer (`answer_a` upstream), and the section path.
2. Identify *why* the correct answer is correct. Reach for a
primary source before paraphrasing 50ohm.de.
3. Draft the body per §4, pick a source per §6, score honestly
per §5.
4. Open `explanations.json`, insert the new entry in **alphabetical
key order**, save.
5. Run `python3 -m unittest test_amateurfunk_anki` — the schema
validator runs as part of the build path used by tests, so a
typo'd entry fails fast.
6. Rebuild decks (`make anki`) and spot-check the new entry on
the back of the card.
### 8.2 "Explain every question that doesn't have an entry yet"
This is bulk work — handle it in chunks, not as one giant batch.
1. Compute the unexplained set:
```sh
python3 -c '
import json, glob
catalog = next(iter(glob.glob("data/*/fragenkatalog*.json")))
exp = json.load(open("explanations.json"))
def walk(n):
for q in n.get("questions", []) or []: yield q["number"]
for s in n.get("sections", []) or []: yield from walk(s)
missing = sorted(set(walk(json.load(open(catalog)))) - exp.keys())
print(len(missing), "questions unexplained")
print("\n".join(missing[:20]))
'
```
2. Process in groups of ~10 within one topic. Same section path
often shares one source citation, so context stays warm and
confidence scores stay consistent.
3. After each group, save and run the tests. Don't accumulate
hundreds of unsaved entries.
### 8.3 "Improve all entries with confidence below N"
1. List low-confidence entries:
```sh
python3 -c '
import json
exp = json.load(open("explanations.json"))
for k, v in sorted(exp.items()):
if v["confidence"] < 7: print(k, v["confidence"], "—", v["source"])
'
```
2. For each, look up the question (§3), seek a stronger source
(§6), rewrite if the new source changes the framing.
3. **Bump `revision`** and update `confidence` to reflect the new
evidence. Do not just bump confidence without changing anything
else — that's how bad explanations entrench themselves.
### 8.4 "This explanation is wrong"
1. Read the current entry. Confirm the error against the catalog
stem and the cited source.
2. Rewrite the body, replace the source if needed, bump
`revision`, and re-score `confidence` from scratch (don't carry
over the prior score).
3. Commit message should name the question number and summarize
what was wrong — future agents need to know what kind of
mistake to look for elsewhere.
---
## 9. Validation checklist
Before saving, confirm:
- [ ] Key is the exact catalog `number` (case-sensitive).
- [ ] All four fields present, correct types, in range.
- [ ] `explanation` is English, terse, WHY-focused.
- [ ] `source` is non-empty and as primary as possible.
- [ ] `revision` is correct (1 for new, bumped for improvement).
- [ ] `confidence` honestly reflects how well the source supports
the explanation.
- [ ] Keys remain in alphabetical order in the file.
- [ ] `python3 -m unittest test_amateurfunk_anki` passes.
---
## 10. What's out of scope here
- **Translating questions into English.** The cards are bilingual
by design: German question + English explanation. Don't
paraphrase the German.
- **Editing the catalog itself.** `data/` is a build artifact —
refreshed by `amateurfunk_fetch.py` from BNetzA. Mistakes in the
upstream questions are upstream's to fix.
- **Removing explanations.** If an entry is genuinely useless, fix
it forward (§8.4). Don't delete keys — that loses the audit
trail. (The schema doesn't currently encode "retracted", so if
you ever need it, propose a schema change.)