syntherklaas

name

syntherklaas

description

Generate synthetic data from scratch through an interactive dialog — ask the user table-by-table about columns, types, foreign keys, and constraints; render the data model as ASCII UML; ask for volume + distributions; then generate consistent fake data with Faker (locale-aware) + NL-locked providers for BSN/IBAN/postcode. Outputs CSV (loose files), XLSX (loose or multi-sheet), or SQLite. Schema can be saved to YAML for re-invoke (`/syntherklaas <yaml-path>` skips the dialog, runs deterministic generation). Use when the user wants test data, demo data, fake data with FK relations, or mentions "synthetic data", "fake data", "test data", "demo dataset", "BSN-safe test data", or "anonimiseer me een schema".

syntherklaas

Interactive synthetic data generator. Two invocation paths:

1. Full dialog (/syntherklaas) — build the data model from scratch.
2. Re-invoke (/syntherklaas <yaml-path>) — load a previously-saved schema, confirm, run.

Pipeline: dialog → schema-YAML → Faker + numpy (deterministic seed) → topo-ordered DataFrames → writer (CSV-loose / XLSX-loose / XLSX-multi / SQLite).

Dispatch

When the user invokes the skill, branch on the argument:

• Argument is a .yaml or .yml file that exists → go to Re-invoke path below.
• No argument, or other text → go to Full dialog path below.

---

Re-invoke path

1. Load the YAML via bash "${CLAUDE_SKILL_DIR}/scripts/run.sh" --schema <path> --preview to validate it and obtain a JSON preview (the script returns exit code 2 on a malformed YAML).
2. Render a confirmation summary in chat — list the tables, locale, seed, output target (from the YAML's output block if present), and a 10-row preview per table.
3. Ask: "OK om te genereren? (ok / annuleer)".
4. On ok:
   • If the YAML already has an output block, run bash ${CLAUDE_SKILL_DIR}/scripts/run.sh --schema <path> (it picks up format+path from the YAML).
   • Otherwise ask the user for format + path, then run bash ${CLAUDE_SKILL_DIR}/scripts/run.sh --schema <path> --output <out> --format <fmt>.
5. On annuleer — stop.

---

Full dialog path

Greet the user briefly, then proceed through the phases below. The user may say "stop" at any point to abort.

Phase 0 — Locale

Ask: "Faker-locale? (default: nl_NL — accepteert bv. en_US, de_DE, fr_FR, ...)"

Note: NL-locked providers (nl.bsn, nl.iban, nl.postcode, nl.phone, nl.tussenvoegsel) always emit NL-formatted values regardless of session locale. Mention this if the user picks non-NL and the schema later includes any nl.* provider.

Phase 1 — Schema discovery (loop per table)

For each table:

1. Ask: "Tabelnaam?"

2. Ask: "Hoe wil je de kolommen van <tabel> definiëren?" with three options:

   • Paste voorbeeld-data — plak een paar regels CSV-achtig of freeform; ik leid kolommen + types af.
   • Samen definiëren — we lopen kolom-voor-kolom door (naam + voorbeeld), tot je klaar zegt.
   • Doe een voorstel — ik stel zelf kolommen voor op basis van de tabelnaam.

3. Branch:

   • Paste: user pastes CSV-like rows or freeform examples. Extract column names + 1-5 sample values per column.
   • Guided: loop "kolomnaam? voorbeeld(en)? volgende of klaar?" until the user signals done.
   • Voorstel: propose 5-10 plausible columns directly from the table name — each met een naam, type, gekozen provider en 1-2 voorbeelden — en spring meteen door naar de confirm-tabel (step 5; provider-inferentie heb je al in het voorstel gedaan). Als de tabelnaam te dun is om iets zinnigs te verzinnen (bv. data, items, records, tabel1, temp, eenletterige namen): vraag eerst "Waar is <tabel> voor?" en bouw het voorstel op basis van dat antwoord. Bij concrete namen (klanten, orders, email_campagnes, facturen, producten, medewerkers, ...) niet eerst vragen — stel direct voor en laat de user in step 6 corrigeren.

4. Based on column names + sample values, infer a provider per column from this table:

   Provider name	When to pick
   sequential + primary_key: true	always for an id column
   faker.name	column looks like a person name
   faker.email	column looks like an email
   faker.phone_number	non-NL phone, or generic phone
   faker.address	generic address
   faker.company	company name
   faker.text	free-form text / notes
   nl.bsn	NL BSN
   nl.iban	NL IBAN
   nl.postcode	NL postal code (1234 AB)
   nl.phone	NL mobile (06-XXXXXXXX)
   nl.tussenvoegsel	NL surname infix
   numeric_range	integer/float with bounds (age, price, count, ...)
   categorical	small fixed set of values (status, type, ...)
   datetime_range	timestamp or date in a window
   fk	<table>_id columns or otherwise clearly referencing another table

5. Render a confirm table:

   | col       | provider          | constraint     | voorbeeld     |
   | id        | sequential        | PK             | 1, 2, 3, ...  |
   | naam      | faker.name        | NOT NULL       | (Faker name)  |
   | bsn       | nl.bsn            | UNIQUE         | 123456782     |
   | leeftijd  | numeric_range int | min 18, max 80 | 42            |
   | status    | categorical       | choices=[...]  | active        |
   

6. Conditional values — detect cases where a column should only be populated when another column has a specific value (klassiek voorbeeld: url alleen gevuld bij event_type=click; cancelled_at alleen bij status=cancelled). Use the when-clause on the dependent column:

   - name: url
     provider: faker.url
     when:
       column: event_type
       equals: click          # scalar of lijst, bv. [click, custom_click]
       # else_value: <value>  # optioneel; default null
   

   Rules: when.column moet eerder in dezelfde tabel staan (validator dwingt dat af) en mag niet op sequential / fk / PK kolommen. Stel when proactief voor wanneer de naam-combinatie het suggereert; render in de confirm-tabel met constraint when event_type=click.

7. Ask: "Klopt? (ok / wijzig kolom )". On wijzig: update the column and re-render, loop until ok.

8. Ask: "Foreign keys naar andere tabellen? (bv. user_id → users.id of geen)". Add as fk-provider columns.

9. Ask: "Nog een tabel of klaar?". Loop until klaar.

Phase 2 — ASCII UML

Topo-sort the tables and render boxes with columns + relations with cardinality. Style:

┌─────────────────────────┐         ┌──────────────────────────┐
│ users                   │ 1     * │ events                   │
├─────────────────────────┤─────────┤──────────────────────────┤
│ id (PK)         INT     │         │ id (PK)          INT     │
│ naam            STR     │         │ user_id (FK)     INT ────┤
│ bsn (UQ)        STR     │         │ kind             STR     │
│ leeftijd        INT     │         │ occurred_at      DATETIME│
└─────────────────────────┘         └──────────────────────────┘

Use 1..* notation on the edges. Ask: "Klopt het model? (ok / wijzig )".

Phase 3 — Volume + distributies

Before asking the first volume question, send een korte intro-message (geen AskUserQuestion) die uitlegt wát we nu gaan vastleggen en wat de keuzes betekenen. Voorbeeld-strekking (parafraseer, niet letterlijk kopiëren):

We bepalen nu hoeveel rijen elke tabel krijgt. Per tabel kies je een verdeling:

• Vast — exact dit aantal rijen (bv. 1000). Geen variatie.
• Poisson λ=N — N als gemiddelde, met natuurlijke variatie rond dat getal. Past bij "ongeveer N events per gebruiker" of "ongeveer N orders per dag".
• Normal μ±σ — klokvormig rond μ met spreiding σ. Past bij "rond de 500, meeste tussen 400 en 600".
• Uniform min-max — elk getal in [min, max] even waarschijnlijk. Brede gelijke spreiding. Voor child-tabellen geldt dit per parent-rij (per_parent); voor root-tabellen geldt het als totaal.

Pas de exact gepresenteerde opties in elke AskUserQuestion aan de tabel-context aan (bv. concrete λ/μ/min-max-suggesties op basis van wat de user eerder zei).

For each table in topological order, ask via AskUserQuestion:

• Root (no FK): "Hoeveel rijen voor <tabel>?" — bied 4 keuzes: een redelijke vaste waarde, een poisson, een normal, en een uniform. Concrete getallen invullen.
• Child (has FK with per_parent semantics): "Hoeveel <tabel> per <parent>?" — zelfde 4 opties, schaling per parent. Als user expliciet een totaal noemt, accepteer dat en val terug op count semantics.

For each datetime_range column: ask "tijdsperiode? (bv. 2024-01-01..2024-12-31; uniform of normal)".

For each numeric_range column: ask "range? (bv. 18-80 uniform of 35±12 normal)".

For each categorical column: ask "gewichten? (uniform of bv. 60/30/10 voor 3 choices)".

Translate user shorthand into the schema-YAML format (see examples/demo-schema.yaml).

Phase 4 — Build YAML + preview

1. Write the schema to /tmp/syntherklaas-<sessid>/schema.yaml (mkdir-p first; use a fresh UUID or timestamp suffix).
2. Run: bash "${CLAUDE_SKILL_DIR}/scripts/run.sh" --schema /tmp/.../schema.yaml --preview
3. Parse the JSON preview and render Markdown tables (max 10 rows per table) in chat.

Phase 5 — Output

1. Ask: "Tevreden? (ok / regenerate met andere seed / wijzig schema)".
   • regenerate: edit the YAML to add a new seed: <random_int>, re-run preview.
   • wijzig: drop back to the relevant phase (1/2/3) to edit.
2. Ask: "Output-formaat?"
   1. csv-loose — losse CSV-bestanden (in een directory)
   2. xlsx-loose — losse XLSX-bestanden (in een directory)
   3. xlsx-multi — één multi-sheet XLSX
   4. sqlite — SQLite database (.db / .sqlite)
   5. postgres — één .sql-dump met PostgreSQL-dialect CREATE + INSERT
   6. mssql — één .sql-dump met Microsoft SQL Server dialect
3. Ask: "Output-pad?" (file for xlsx-multi / sqlite / postgres / mssql, directory for csv-loose / xlsx-loose).
4. Update the schema-YAML to include the chosen output: {format, path} block.
5. Run: bash "${CLAUDE_SKILL_DIR}/scripts/run.sh" --schema /tmp/.../schema.yaml --output <path> --format <fmt>
6. Report file paths + per-table row counts (the CLI prints these on stdout).

Phase 6 — Save schema

Ask: "Wil je dit schema opslaan voor herbruik? (geef een pad, of zeg nee)".

On a path: cp /tmp/syntherklaas-<sessid>/schema.yaml <user-path> and confirm with:

"Volgende keer kun je het reproduceren met: /syntherklaas <user-path> — dan toon ik alleen een confirmatie en draai dezelfde generatie."

Exit codes

• 0 — success
• 2 — schema/output/format problem (malformed YAML, unknown provider, FK to unknown column, output path conflict, Excel limit exceeded, ...)
• 3 — cyclic FK detected
• 4 — missing dependencies (uv not on PATH)

Reference

• Pipeline modules in scripts/: providers.py (Faker + NL extras + numpy distributies), schema.py (YAML validator), generate.py (orchestrator + CLI), writers.py (dispatch), sqlite_writer.py, xlsx_writer.py, fk_resolver.py (topo-sort).
• Tests: scripts/tests/ (run via uv run pytest).
• Worked example: examples/demo-schema.yaml (3-table klanten/orders/orderlines + distributies) + examples/transcript.md (session walkthrough).