Synthdata Interactive Tutorial

Starting the Tutorial

When triggered, introduce the walkthrough conversationally:

I'll walk you through synthdata's key capabilities with a working example. We'll tour the built-in templates, generate a dataset, write a custom YAML schema for something outside the catalog, extract it to JSON, extend it with more rows, anonymize a "real-looking" file, and serve a dataset as an MCP server that Claude can query. About 15-20 minutes. Ready?

Wait for confirmation before proceeding. Also ask: "Any particular domain you'd rather use?" — if they say e-commerce, healthcare, IoT, etc., swap the template in Step 1 accordingly. Otherwise default to hr-directory (small, fast, easy to reason about).

The Tutorial Arc

Step 1: Tour the templates — "What can I generate out of the box?"

Skill used: synthdata-generate What it demonstrates: The 12 built-in templates — each is a production-ready schema you can use as-is or fork.

List the templates:

python3 <synthdata-generate>/scripts/generate.py --list-templates

Walk the user through the catalog. Group them so it's easier to scan:

People & orgs

• hr-directory — employees, departments (2 tables, classic starter)
• crm-pipeline — contacts, companies, deals, activities (sales pipeline)

Commerce & finance

• ecommerce-orders — customers, products, orders, order_items (4 tables, FK chains)
• financial-transactions — accounts, customers, transactions
• saas-metrics — accounts, users, events, subscriptions (usage + billing)

Healthcare

• healthcare-patients — patients, providers, encounters, claims
• healthcare-hrm-security — users, threat events, phishing sims, training, DLP, monthly risk (7 tables, richest template)

Operations & telemetry

• security-events — users, devices, alerts, incidents
• log-events — services, requests, errors
• iot-sensors — devices, readings, events
• survey-responses — respondents, questions, responses

Custom starter

• blank-slate — minimal schema to fork for your own domain

Explain the three knobs that apply to every template:

• Template — pick one above, or start from blank-slate
• Effort — quick (~50-100 rows), medium (~1K), thorough (~5K+). Scales row counts and event density but leaves schema shape intact.
• Format — xlsx (multi-sheet workbook with title banners), csv, json, sql, parquet.

Offer to peek inside a template YAML so they see what a schema actually looks like:

cat <synthdata-generate>/templates/hr-directory.yaml

Point out the anatomy: name:, tables:, per-table rows: (with quick/medium/thorough tiers), columns: with typed fields (id, faker, choice, int, float, date), optional profiles: (behavioral segments), foreign_key: links between tables, and writers: at the bottom. This is the same format they'll write from scratch in Step 2.

Now generate the chosen template at medium effort:

python3 scripts/generate.py --template hr-directory --effort medium \
    --output /tmp/synthdata-tutorial/hr.xlsx --seed 42

Show the user the output — row counts per table, foreign-key integrity (e.g., every employee.department_id resolves to a departments.department_id), and column distributions (department weights, tenure mean, salary lognormal).

Bridge:

Twelve templates cover a lot of ground, but not everything. What if you need something that isn't in the catalog — say, a fleet of delivery drivers with route assignments?

Step 2: Custom schema — "Write your own YAML"

Skill used: synthdata-generate What it demonstrates: The schema format is the real product. Templates are just pre-written YAML — users can write their own for any domain.

Write a minimal two-table schema to a file. Use something concrete that isn't in the catalog so it feels distinct from Step 1 — delivery drivers + trips works well:

cat > /tmp/synthdata-tutorial/drivers.yaml << 'EOF'