digitalarchivst/open-genealogy/gedcom-creator

GEDCOM Creator — GEDCOM 5.5.1 File Generator

Create standards-compliant GEDCOM 5.5.1 files from user-provided genealogical data. Accepts natural language, structured JSON, or markdown tables.

This tool records only what you provide. It never invents people, dates, or places.

Design Principle

The LLM parses and reasons. Code handles mechanics.

You (Claude) interpret user input and build a canonical JSON intermediate. The Python script (scripts/gedcom_builder.py) handles GEDCOM rendering, pointer wiring, CONC/CONT splitting, validation, and file output. You NEVER generate raw GEDCOM text directly.

Dependencies

Python 3.6+ standard library only. No pip install required.

When to Auto-Invoke

Auto-invoke when the user wants to create, generate, or build a GEDCOM file from genealogical data. Trigger phrases:

• "create a GEDCOM"
• "generate a GEDCOM file"
• "build me a GEDCOM"
• "turn this into a GEDCOM"
• "export this as GEDCOM"
• "make a .ged file"

Do NOT auto-invoke for GEDCOM reading, analysis, or visualization.

What You Can Say

Example prompts to get started:

"Create a GEDCOM for my grandmother Rose Marie Sullivan, born
April 3, 1928 in Boston, Massachusetts, died February 14, 2015
in Quincy, Massachusetts. She married Thomas Patrick O'Brien on
September 12, 1950 in Boston."
 
"Here's census data I extracted — turn it into a GEDCOM file:
[paste table]"
 
"Generate a GEDCOM from this JSON: [paste structured data]"

Image Input

When the user uploads an image (document, chart, headstone, certificate, screenshot) instead of text:

1. Describe what you see: document type, layout, readability.
2. Extract what you can read with confidence.
3. For text you cannot read clearly, use [illegible] as a

placeholder value and note it.

1. For structural positions visible but unnamed (e.g., a box in

a pedigree chart with unreadable text), create the individual as Unknown /Unknown/ and preserve family links.

1. When an image explicitly shows gender (colored icons, M/F

markers, or HUSB/WIFE column position), use it. The prohibition on assuming gender from names does not apply to explicit visual indicators.

1. Report what you could and could not read before showing the

confirmation preview.

Pedigree charts: The subject is at the left or center. Lines connect to ancestors (parents, grandparents), not spouses. Spouses may appear adjacent but are linked by marriage, not descent. Read carefully — do not confuse a parent with a spouse.

Processing Pipeline

Step 1: Detect Environment

echo "MSYSTEM: $MSYSTEM" && uname -s && which python 2>/dev/null || which py 2>/dev/null || echo "python not found"

Determine the correct Python command and script path:

Step 2: Parse User Input to JSON Intermediate

Accept input in any of four modes:

Mode 1 — Conversational (Primary): Parse natural language descriptions of people and families into the canonical JSON format. This is the most common input path.

Mode 2 — Structured JSON (Advanced): Accept JSON matching the canonical schema (see below). Validate and pass through.

Mode 3 — Markdown Table (Advanced): Parse tabular data into the canonical JSON format.

Mode 4 — Image (Vision): Follow the Image Input protocol above, then build the canonical JSON from extracted data.

Parsing Rules

• Extract every individual mentioned with all stated facts
• Identify family relationships (spouse, parent, child)
• Normalize dates to GEDCOM format (see Date Mapping below)
• Normalize places to 4-level depth when possible

(Locality, County, State, Country)

• NEVER invent data not explicitly stated by the user
• NEVER narrow imprecise dates ("the 1920s" is NOT "ABT 1925")
• When the same name appears multiple times, treat as the same

person unless context indicates otherwise. If ambiguous, ASK.

• Contradictions across sources: When different documents disagree,

present both readings and ask the user to resolve.

• Contradictions within a single source: Record the most internally

consistent reading. Add a NOTE documenting both values and flag it in the confirmation preview. Example: "Source gives marriage as both 1789 and 1791. ABT 1789 used; user should verify." Tiebreaker: If no reading is more internally consistent than another, record BOTH readings in a NOTE and leave the DATE field empty. Flag for user resolution in the confirmation preview. Do not silently pick one.

• For gender, use what the user states or U if unknown.

NEVER assume gender from names.

Parish Register Table Formats

When the user provides data from English parish registers, expect these table structures:

Baptisms:

| Date | Child | Father | Mother | Notes | Source |
| 14 Feb 1603/04 | William | William Whitchurch | | | PR, f.12r |
| 3 May 1606 | Robert | William Whitchurch | Anne | | PR, f.14v |
| 11 Jan 1610/11 | Samuel | William Whitchurch | | base born | PR, f.17v |

Parsing notes for baptisms:

• Mother is frequently absent in pre-1640 registers. Do NOT infer

her. Treat blank as unrecorded, not "unknown wife."

• "base born" / "bastard" / "illegitimate" means no father should

be assigned to the family unit. Link child to mother only.

• Use BAPM (baptism) for English parish register entries, not

CHR (christening) unless the register explicitly says christening.

• Folio references (f.12r, f.14v) are standard manuscript citations.

Marriages:

| Date | Groom | Bride | By | Notes | Source |
| 15 Oct 1601 | William Whitchurch | Anne [unknown] | banns | | PR, f.8r |
| 22 Nov 1635 | Robert Whitchurch | Jane Harding | licence | | PR, f.31v |

Parsing notes: "By" column (banns/licence) is genealogically significant. Bride's maiden surname is often absent in early registers — do NOT fabricate it.

Burials:

| Date | Name | Descriptor | Notes | Source |
| 8 Mar 1641/42 | William Whitchurch | senior | | PR, f.42r |
| 14 Jun 1643 | Anne Whitchurch | wife of William | | PR, f.43v |
| 2 Dec 1680 | William Whitchurch | | | PR, f.67r |

Parsing notes: The Descriptor column is critical for disambiguation. Preserve descriptors verbatim ("senior," "the elder," "wife of William," "widow," "son of Robert"). These are primary disambiguation evidence. A burial with no descriptor in a period when multiple people share the name is genuinely ambiguous — flag it in the confirmation preview with an AMBIGUOUS: prefix and list candidate IDs. Do not create a GEDCOM record for the burial until the user resolves which individual it belongs to.

Important: When a burial entry mentions a person (e.g., "Anne, wife of William"), ensure that person gets a BURI event on their own INDI record — not just a mention in someone else's NOTE. This helps the living-person filter correctly identify them as deceased.

Wills (supplementary):

| Date | Testator | Relationships | Probate | Source |
| 12 Jan 1641/42 | William Whitchurch | wife Anne; son Robert; son William; dau Joan | 3 Apr 1642 | TNA PROB 11/189 |

The Relationships column provides direct evidence for family links. Each named relationship becomes a source citation on the FAM record (see Family-Level Source Citations below).

Name Disambiguation for Recycled Names

When processing registers where the same given names repeat across generations (e.g., successive William Whitchurches), maintain a mental "person register" with active date windows:

Step 1: Assign active windows. Each known individual gets a plausible active range: baptism + 16 years to baptism + 55 years (for fathering children).

Step 2: When a new entry names a person, check candidates.

• Exactly one candidate in the active window: assign

tentatively. Add a NOTE: "Assigned to [ID] based on date plausibility."

• Zero candidates: create a new individual. Add a NOTE:

"New individual — no existing candidate in active window."

• Multiple candidates: DO NOT ASSIGN. Flag as ambiguous:

"AMBIGUOUS: [entry] could be [I3] (bapt. 1580) or [I7] (bapt. 1610). User must resolve."

Step 3: Use register descriptors as primary evidence. "Senior" / "junior" / "the elder" / "wife of" / "son of" — these disambiguate directly. Note: in English registers, senior/junior means elder/younger currently alive in the parish, NOT necessarily father/son.

Step 4: Use wills to confirm or resolve. A will naming "my son William" written by a William who was buried the following week is direct relationship evidence.

Step 5: Use spousal co-occurrence. If baptism entries name the mother as "Anne" from 1601-1615 and "Joan" from 1618-1630, check the burial register for an Anne between 1615-1618. If found: one man, sequential wives. If not: possibly two different men.

NEVER silently merge ambiguous individuals. Present all ambiguities in the confirmation step for the user to resolve.

Date Mapping

The builder accepts these canonical lexical forms:

• A three- or four-digit year, MON YEAR, or DAY MON YEAR, with an

optional dual year such as 1731/32

• A simple date prefixed by ABT, BEF, AFT, CAL, or EST
• BET date AND date
• FROM date TO date, FROM date, or TO date

Months must use uppercase GEDCOM abbreviations. Natural-language, numeric ISO, calendar-escape, and interpreted INT phrases are not accepted in the JSON intermediate. Omit an unknown date instead of guessing. Validation is lexical; it does not prove that a date existed on a particular calendar.

Step 3: Show Confirmation (MANDATORY)

Before generating the GEDCOM, display a human-readable summary and ask the user to confirm. This step is NOT optional.

Format:

=== GEDCOM Preview ===
 
Individuals: [count]
Families: [count]
Sources: [count]
 
| ID | Name | Birth | Death | Family Role |
| -- | ---- | ----- | ----- | ----------- |
| I1 | John Smith | 15 MAR 1845, Richmond, VA | 2 JAN 1920, Henrico Co, VA | Spouse in F1 |
| I2 | Mary Jones | | | Spouse in F1 |
| I3 | William Smith | 1870 | | Child in F1 |
 
Families:
  F1: John Smith (I1) + Mary Jones (I2) → William Smith (I3)
 
Date interpretations:
  - "around 1868" → ABT 1868
 
[For images: "Extracted X of ~Y visible individuals.
Z positions were not readable — created as Unknown."]
 
Shall I generate the GEDCOM file?

Family Role column format:

• Single role: Spouse in F1 or Child in F1
• Multiple roles: Child in F1; Spouse in F2 (semicolon-separated)
• No family links: Unlinked

This column is derived from family_child and family_spouse in the JSON — it is display-only and not stored.

If the user says yes (or equivalent), proceed. If they correct anything, update the JSON intermediate and re-confirm.

Step 4: Generate GEDCOM via Python Script

Write the canonical JSON to a temp file, then invoke the builder:

# Write JSON intermediate to temp file
cat > /tmp/gedcom_input.json << 'JSONEOF'
[paste the canonical JSON here]
JSONEOF