settled-reach/docs/gemma-naming-methodology.md

Gemma Naming Methodology (institutional knowledge)

Status: the implementing code (gemma_naming.py, naming_core.py, and the test_batch_naming.py / qa_naming.py harnesses) was retired in #951 (D-223) when authored markers became a names-only flavoured pool and the per-feature geometry generator was retired. This document preserves how the Reach's place names were generated so the approach can be rebuilt for the names-only format if new bodies ever need fresh names. The names it produced are now the frozen pool in each markers.json (names.{rivers,mountain_ranges,oceans,cities,pois,...}).

The pipeline named every empty name field across ~2,400 bodies' markers.json files (cities, rivers, oceans, mountain ranges, gate terminals, landmarks) with culturally-coherent, corridor-appropriate names — using a small local LLM, not a hand-written name table.

---

1. Model & runtime

• Model: Gemma 2 2B (gemma2.gguf), later gemma-4.gguf — a small local GGUF model, chosen so the whole Reach could be named offline on commodity hardware (CPU fallback, ROCm/CUDA when available).
• Serving: sr-voice serve --stdio — a long-lived subprocess fed prompts over stdin, replies over stdout. The same binary backs the in-game voice pipeline.
• KV-cache bleed is the enemy. A long-lived model accumulates context across requests and starts echoing earlier completions (every river becomes "Aldren"). The subprocess was restarted every --refresh requests to flush the cache. This single knob mattered more than any prompt tweak for output diversity.

2. Two-stage flow

1. Register selection (select_register) — for each star system, Gemma is shown the corridor's candidate cultural sub-styles (numbered) plus a compact cultural excerpt from the system's wiki + GTTR text, and asked to pick the number of the best-fitting register. This grounds naming in the authored cultural identity rather than a blind hash. Falls back to palette_for (hash-based pick) if the model fails or there's no cultural text.
2. Name generation (_build_prompt) — generate names in the selected register, per feature, with retries and dedup.

3. Corridor palettes — the cultural-design crux

Names are biased by geographic sector (the real corridor column in systems.db is star_systems.geographic_sector). Each sector has a list of sub-style inflections, each with a register description and ~5 example stems. A sub-style is picked per system (via hash(system_id)) so neighbouring systems rotate registers and the model's narrow ~15-stem vocabulary stays fresh across hundreds of bodies.

Inflection is a dominant bias, not a hard lock. A British surveyor on an east_reach moon still names a river after their aunt in Dorset. Each sub-style explicitly names its register and invites diaspora variety. This is what keeps the Reach feeling like blended-reality settlement rather than themed zones.

Sector	Sub-style registers
core	English countryside · British colonial · American frontier · American municipal · Classical/civic · ANZ settler
north_reach	English rural/parish · Scottish Highland/Lowland · Australian outback · Irish coastal · South African English
south_reach	Portuguese colonial/Iberian · Brazilian interior · East African Swahili · Cape Verdean/West African · Angolan/Mozambican
east_reach	Korean · Japanese rural/coastal · Taiwanese/Hakka · Filipino · Mixed East Asian diaspora
west_reach	German compound · Dutch low-country · Nordic/Scandinavian · Polish/Czech · Baltic/Finnish
deep_frontier	Founder-surname · Surveyor-descriptive · Functional/military outpost

Legacy aliases mapped to core (sol-gateway-axis, inner_corridor, inner_orbit) and deep_frontier (frontier). Cross-cultural names in every direction are expected and correct (see the corridor cultural-mixing principle).

4. Few-shot prompting (the model-fit lesson)

Gemma 2 2B is far better at pattern completion than instruction following.

So prompts were worked examples, not instructions:

• Show 2 examples from different corridors than the target (teach the pattern — "system description → register number" or "register → place name" — without biasing toward the target's vocabulary), then present the target and let the model complete.
• Register selection used a fixed preamble with two System: … → Best: N examples, then the target system, then Best (number only):.
• Per-feature generation rotated through example pools picked deterministically by hash(body_id, local_id, attempt) so neighbouring features on one body don't all draw the same prompt and collapse to identical outputs.

5. Context extraction (fitting 1024 tokens)

Gemma 2 2B has a ~1024-token context, so the authored cultural signal had to be compressed hard:

• GTTR hook — the 30–45 word "Drifter's Guide" characterisation of the system is the single biggest lever for names that feel like this world. Title lines and section headers were stripped; the first substantive paragraph was used.
• Wiki cultural lines — _extract_cultural_lines scanned for cultural-identity keywords (heritage, founding, settler, surname, language, diaspora, and explicit culture names) and kept the strongest hits, falling back to opening prose.
• Budget math reserved tokens for preamble + tail + output; context was truncated to fit.

6. Post-processing, retries, dedup, fallback

• Deterministic seeds: seed = sha256("{role}|{id}|{attempt}").hexdigest()[:8] — reproducible, and bumping attempt rotates the completion on retry.
• Earth-major blocklist: earth_blocklist.txt rejected real Earth majors (Paris, Tokyo, …). Earth-echo names are fine; Earth majors are not.
• Retry: on collision or blocklist hit, retry with a bumped seed, up to 3 attempts.
• Deterministic fallback: persistent failure fell back to a palette-driven stem+suffix name (fallback_name, _FALLBACK_STEMS/_FALLBACK_SUFFIXES) so the pipeline always produced something valid.
• Dedup scope: within (geographic_sector, feature_type) — no two bodies in the same sector ship the same river name; cross-corridor collisions are allowed (two "Aldren"s on opposite arcs is fine). Processing ran core-first (SECTOR_PRIORITY) so core bodies won the dedup race and outer sectors took the fallback path on collision.

7. Per-feature prompt config

Each feature type had its own subject framing, length hint, and example pools (_PROMPT_CONFIG): rivers/oceans/seas/lakes/mountain ranges → "1–3 words"; capital → "1–2 words" (+ planet context); secondary towns → "1–2 words"; gate terminals → "2–3 words ending in 'Gate Terminal'/'Transit'/'Exchange'/ 'Concourse'"; institutional & cultural landmarks → "2–4 words". Capitals and secondary towns included planet context so town names sat under the world's name.

8. If you rebuild this for names-only markers

The data model changes: there are no longer per-feature records with empty name fields to fill — the target is the flat name pool per body (names.cities, names.rivers, …). A rebuild would:

1. Decide pool sizes per body (how many city/river/etc. names to mint).
2. Keep stages 1–6 verbatim — register selection, corridor palettes, few-shot completion, seed/dedup/blocklist/fallback are all format-independent.
3. Write strings into names.<category> lists instead of into feature records, and drop the atlas-DB sync entirely (the server cascade attaches pooled names to computed features at placement — D-223, #955).