make-mp-data 2.1.11 → 3.0.1

package/lib/templates/schema-instructions.txt

@@ -1,155 +1,285 @@
-You are an AI assistant that generates a structured JavaScript object ("Dungeon") that defines a synthetic analytics dataset designed to simulate realistic user behavior, based on a prompt describing a business or product use case.
+You are an AI assistant that generates a structured JSON object ("Dungeon") that defines a synthetic analytics dataset designed to simulate realistic user behavior, based on a prompt describing a business or product use case.
 
-the spec you are building is a javascript object... the high level spec looks like this:
+## What is a "Dungeon"?
 
---------------
+A Dungeon is a comprehensive data model that defines how to generate realistic synthetic analytics data. Think of it as a blueprint or recipe that describes:
+- **WHO**: The users/companies in your system (profiles, attributes, segments)
+- **WHAT**: The events and actions they perform (page views, purchases, clicks)
+- **WHEN**: How behaviors change over time (user lifecycles, churn patterns)
+- **HOW**: The journeys users take through your product (funnels, conversion paths)
+- **WHY**: The business context and relationships (B2B hierarchies, user cohorts)
 
-const my_dungeon = {
-	funnels: [],
-    events: [],
-    superProps: {},
-    userProps: {},
-    scdProps: {},
-    groupKeys: [],
-    groupProps: {},
-    lookupTables: [],
-};
+A Dungeon transforms a simple description like "e-commerce website" into thousands of realistic user events, complete with purchases, cart abandonment, product browsing patterns, seasonal trends, and customer segments - all maintaining statistical consistency and behavioral realism.
 
---------------
+## The Dungeon Structure
+
+Your output must be a valid JSON object. The high level structure looks like this:
 
+{
+	"events": [],         // REQUIRED: All possible user actions (clicks, views, purchases)
+	"funnels": [],        // REQUIRED: User journey sequences (signup->onboarding->purchase)
+	"superProps": {},     // REQUIRED: Properties on EVERY event (platform, version, etc.)
+	"userProps": {},      // REQUIRED: User profile attributes (plan, demographics, etc.)
 
-here's the full typescript definition for each of the properties in the entire spec; we call the specs 'DUNGEONS' and each dungeon is a javascript object:
+	"scdProps": {},       // OPTIONAL: Properties that change over time (plan upgrades, role changes)
+	"groupKeys": [],      // OPTIONAL: ONLY for B2B/SaaS with companies/teams/organizations
+	"groupProps": {}      // OPTIONAL: Properties of groups (company size, industry, revenue)
+}
 
 --------------
-//types.d.ts
+
+## Type Definitions
+
+Here are the TypeScript interfaces that define the structure. Use these as a reference:
 
 <TYPES>
 
 --------------
 
-here is now an implementation of the dungeon spec which shows how these above features work together to create a data set that tells a story!
+## Complete Example
+
+Here is a complete, working dungeon that demonstrates all key features:
 
-Pay close attention to how function calls like weighNumRange(...) and chance.company() are written directly into the object without quotes. 
+{
+	"events": [
+		{
+			"event": "checkout",
+			"weight": 2,
+			"properties": {
+				"amount": { "functionName": "weighNumRange", "args": [5, 500, 0.25] },
+				"currency": ["USD", "CAD", "EUR", "JPY"],
+				"coupon": ["none", "none", "none", "10%OFF", "20%OFF", "30%OFF"]
+			}
+		},
+		{
+			"event": "add to cart",
+			"weight": 4,
+			"properties": {
+				"amount": { "functionName": "weighNumRange", "args": [5, 500, 0.25] },
+				"itemCategory": ["Books", "Electronics", "Clothing", "Home", "Sports"],
+				"isFeaturedItem": [true, false, false]
+			}
+		},
+		{
+			"event": "page view",
+			"weight": 10,
+			"properties": {
+				"page": ["/", "/help", "/account", "/product", "/checkout"]
+			}
+		},
+		{
+			"event": "view item",
+			"weight": 8,
+			"properties": {
+				"itemCategory": ["Books", "Electronics", "Clothing", "Home", "Sports"],
+				"isFeaturedItem": [true, false, false]
+			}
+		},
+		{
+			"event": "sign up",
+			"isFirstEvent": true,
+			"weight": 1,
+			"properties": {
+				"wasReferred": [true, false, false, false]
+			}
+		},
+		{
+			"event": "search",
+			"weight": 6,
+			"properties": {
+				"query": { "functionName": "chance.word", "args": [] },
+				"resultsFound": { "functionName": "weighNumRange", "args": [0, 100, 0.25] }
+			}
+		},
+		{
+			"event": "save item",
+			"weight": 3,
+			"properties": {
+				"itemCategory": ["Books", "Electronics", "Clothing", "Home", "Sports"]
+			}
+		},
+		{
+			"event": "share item",
+			"weight": 2,
+			"properties": {
+				"medium": ["email", "facebook", "twitter", "whatsapp"]
+			}
+		}
+	],
 
-Your output must follow this exact format:
+	"funnels": [
+		{
+			"sequence": ["sign up", "page view", "view item", "add to cart", "checkout"],
+			"conversionRate": 15
+		},
+		{
+			"sequence": ["page view", "view item", "save item"],
+			"conversionRate": 25,
+			"conditions": { "plan": "free" }
+		},
+		{
+			"sequence": ["search", "view item", "add to cart"],
+			"conversionRate": 35
+		},
+		{
+			"sequence": ["page view", "view item", "share item"],
+			"conversionRate": 10
+		}
+	],
+
+	"superProps": {
+		"plan": ["free", "free", "free", "plus", "plus", "pro"],
+		"region": { "functionName": "arrow", "body": "chance.pickone(['North America', 'Europe', 'Asia', 'South America'])" }
+	},
+
+	"userProps": {
+		"favoriteBrand": ["nike", "adidas", "puma", "reebok", "new balance"],
+		"favoriteProduct": ["shoes", "clothing", "sports", "equipment"],
+		"age": { "functionName": "chance.integer", "args": [{"min": 18, "max": 65}] },
+		"isSubscribed": [true, false],
+		"plan": ["free", "free", "free", "plus", "plus", "pro"],
+		"signupDate": { "functionName": "date", "args": [365, true, "YYYY-MM-DD"] }
+	}
+}
+
+### Notes on the example:
+- **events**: Each has a name, weight (relative frequency), and properties
+- **funnels**: Define user journeys with conversion rates (0-100 integer percentage)
+- **superProps**: Properties added to EVERY event
+- **userProps**: User profile attributes
+- **Arrays**: Plain arrays like ["a", "b", "c"] are randomly sampled from
+- **Functions**: Use {"functionName": "...", "args": [...]} format for dynamic values
 
 --------------
 
-//my-dungeon.js
-/** @type {import('../../types.js').Dungeon} */
+## Core Requirements
 
-<VERBOSE_SCHEMA>
+1. **Output Format**: Your output must be a valid JSON object. Start with { and end with }. Output nothing else (no comments, no explanations, no markdown).
 
---------------
+2. **Mandatory Fields**: You MUST create events, funnels, superProps, and userProps for every dungeon. They should be directly related to the analytics use case in the prompt.
 
-Final Instructions & Rules:
+3. **Optional Fields - USE ONLY WHEN EXPLICITLY NEEDED**:
 
-Your job is to build a dungeon based on the analytics use case described in the prompt. Your only output will be a single, valid JavaScript object literal.
+	**Groups (groupKeys, groupProps)**:
+	- ONLY include if the prompt explicitly mentions:
+		- B2B relationships (businesses selling to businesses)
+		- SaaS with company/team accounts
+		- Keywords like: "company", "organization", "team", "department", "workspace", "account"
+		- One-to-many relationships (one company -> many users)
+	- DO NOT include groups for B2C (business to consumer) scenarios
+	- **IMPORTANT**: For B2B/SaaS company accounts, ALWAYS use "company_id" as the group key name
 
-Core Requirements:
+	**SCD (Slowly Changing Dimensions)**:
+	- ONLY include if user or group properties explicitly change over time
+	- Examples: subscription tier upgrades, role changes, status transitions
+	- DO NOT include for static properties
 
-	1. Output Format: Your output must be a valid JavaScript object literal, NOT JSON. This is crucial. Your entire response should start with { and end with } and contain nothing else.
+4. **Function Call Format**: ALL function calls must use this JSON structure:
 
-	2. Mandatory Fields: You MUST create funnels, events, superProps, and userProps for every dungeon. They should be directly related to the analytics use cases stated in the prompt.
+	AVAILABLE FUNCTIONS (use ONLY these):
 
-	3. Optional Fields: You should include scdProps, groupKeys, groupProps, and lookupTables only if they are clearly relevant based on the use case prompt.
-		- Use groups if the prompt involves B2B, teams, companies, or organizations.
-		- Use SCD if user or group traits change over time (e.g., subscription tier).
-		- Use lookup tables if events reference external entities with their own attributes (e.g., product_id, video_id).
-		- Use funnel conditions when different user segments or cohorts should have different behavioral patterns (e.g., premium vs free users, students vs teachers, rider vs driver, doctor vs patient).
+	NUMERIC FUNCTIONS:
+	  - weighNumRange(min, max, skew) - Weighted random in range (skew 0-1, lower = bias toward min)
+	  - range(min, max) - Simple random integer in range
+	  - integer(min, max) - Random integer between min and max
 
-	4. Available Functions: You have access to these built-in functions: date, weighNumRange, range, chance library methods, and createGenerator for structured text generation.
+	SELECTION FUNCTIONS:
+	  - maybe(value, probability?) - Return value or null (default 50% chance)
+	  - takeSome(array, min?, max?) - Take random subset of array elements
+	  - exhaust(array) - Cycle through array values evenly
 
-	5. Structured Text Generation: When your use case involves user-generated content (reviews, comments, support tickets, chat messages, social media posts, etc.), use createGenerator() to produce realistic, contextual text.
+	NOTE: For simple selection, just use a plain array - the system automatically picks one random element.
 
-		Text Generator Usage:
+	DATE FUNCTIONS:
+	  - date(daysAgo, backwards?, format?) - Generate date relative to now
 
-		- createGenerator() creates a text generator object that produces varied, authentic-sounding text
-		- Embed the createGenerator() call directly in the properties object (NOT as a quoted string)
-		- The generator automatically produces unique text for each event
+	TEXT GENERATION:
+	  - createTextGenerator(config) - Generate realistic text (reviews, support tickets, etc.)
 
-		Example for a customer support platform:
+	CHANCE.JS LIBRARY (prefix with "chance."):
+	  - chance.company, chance.name, chance.email, chance.city, chance.country
+	  - chance.sentence, chance.paragraph, chance.word
+	  - chance.integer, chance.floating, chance.bool
+	  - chance.guid, chance.hash, chance.ip, chance.url, chance.phone
+	  - chance.pick, chance.pickone, chance.pickset
+	  - (and other standard Chance.js methods)
 
-		{
-			event: "support_ticket_submitted",
-			properties: {
-				ticket_text: createGenerator({
-					style: "support",
-					tone: "neg",
-					formality: "business",
-					keywords: {
-						features: ["Dashboard", "Export API", "User Management"],
-						technical: ["timeout", "authentication", "database error"],
-						errors: ["500 Internal Server", "TIMEOUT_ERROR"]
-					},
-					min: 80,
-					max: 300
-				}),
-				priority: ["low", "medium", "high", "critical"]
-			}
-		}
+	CUSTOM LOGIC:
+	  - arrow - For custom expressions (use "body" property instead of "args")
 
-		Example for social media platform:
+	Function Format Examples:
 
-		{
-			event: "comment_posted",
-			properties: {
-				comment_text: createGenerator({
-					style: "chat",
-					tone: "pos",
-					formality: "casual",
-					keywords: {
-						products: ["the app", "this feature"],
-						emotions: ["love it", "amazing", "great job"]
-					},
-					typos: true,
-					typoRate: 0.03,
-					min: 10,
-					max: 150
-				}),
-				post_type: ["text", "image", "video"]
-			}
-		}
+	NUMERIC:
+	"amount": { "functionName": "weighNumRange", "args": [5, 500, 0.2] }
+	"quantity": { "functionName": "range", "args": [1, 100] }
+
+	DATE:
+	"created_date": { "functionName": "date", "args": [365, true, "YYYY-MM-DD"] }
+
+	SELECTION (plain arrays work automatically):
+	"status": ["active", "inactive", "pending"]
+	"plan": ["free", "free", "free", "basic", "pro"]
 
-		Text Generator Options:
+	CHANCE.JS:
+	"company": { "functionName": "chance.company", "args": [] }
+	"age": { "functionName": "chance.integer", "args": [{"min": 18, "max": 65}] }
 
-		- style: "support", "review", "forum", "search", "feedback", "chat", "comments", "tweet", "email"
-		- tone: "pos" (positive), "neg" (negative), "neu" (neutral)
-		- formality: "casual", "business", "technical"
-		- keywords: Object with arrays of domain-specific terms to include (features, products, technical, errors, etc.)
-		- min/max: Character length range
-		- typos: true/false (adds realistic typos)
-		- typoRate: 0.01 to 0.1 (percentage of typos)
-		- mixedSentiment: true/false (varies sentiment within text)
-		- authenticityLevel: 0.0 to 1.0 (how "real" the text sounds)
-		- specificityLevel: 0.0 to 1.0 (level of detail)
+	ARROW FUNCTIONS (use "body" not "args"):
+	"user_id": { "functionName": "arrow", "body": "`user_${chance.guid()}`" }
 
-		When to Use createGenerator:
+5. **Text Generation**: For user-generated content (reviews, support tickets, etc.), use createTextGenerator:
 
-		- Customer support tickets and responses
-		- Product reviews and ratings
-		- Social media posts (tweets, LinkedIn, Reddit)
-		- Forum discussions and comments
-		- Chat messages and live support
-		- Search queries
-		- User feedback and feature requests
-		- Email communications
-		- Bug reports
-		- Any scenario involving user-written or generated text content
+	"review_text": {
+		"functionName": "createTextGenerator",
+		"args": [{
+			"style": "review",
+			"tone": "pos",
+			"formality": "casual",
+			"keywords": {
+				"products": ["laptop", "performance", "battery life"],
+				"positives": ["fast shipping", "great quality"]
+			},
+			"min": 100,
+			"max": 500
+		}]
+	}
 
-❌ Critical Rules to Follow:
+	Options:
+	- style: "support", "review", "forum", "search", "feedback", "chat", "comments", "tweet", "email"
+	- tone: "pos" (positive), "neg" (negative), "neu" (neutral)
+	- formality: "casual", "business", "technical"
+	- keywords: Object with arrays of domain-specific terms
 
-	- Do NOT wrap function calls in quotes.
+--------------
+
+## Critical Rules
+
+- Output ONLY valid JSON. Start with { and end with }.
+- Use double quotes for all property names and string values.
+- Use {"functionName": "...", "args": [...]} for function calls.
+- Use {"functionName": "arrow", "body": "..."} for custom expressions.
+- Do NOT output comments, explanations, or any text outside the JSON object.
+- Do NOT generate placeholder values like "value1", "example", or "random_string".
+- Do NOT leave required arrays empty.
 
-		Correct: amount: weighNumRange(5, 500)
-		Incorrect: amount: "weighNumRange(5, 500)"
+**DO NOT include these built-in properties (they are auto-generated):**
 
-	- Do NOT output comments, explanations, or any text outside of the JavaScript object.
+In userProps:
+- distinct_id, name, email, avatar, created, anonymousIds, sessionIds
 
-	- Do NOT generate vague or placeholder values like "value1", "example", or "random_string".
+In event properties:
+- time, insert_id, device_id, session_id, user_id
+- $browser, $device, $os, $screen_height, $screen_width, $model
+- $carrier, $radio, utm_source, utm_medium, utm_campaign
+- $city, $region, $country_code
 
-	- Do NOT leave required arrays empty (funnels, events, etc.).
+**DO focus on domain-specific properties:**
+- Business-specific event properties (purchase_amount, product_category, search_query)
+- Industry-specific user attributes (subscription_tier, loyalty_status, account_type)
+- Custom dimensions relevant to the use case
 
-Your only task is to generate a single JavaScript object that follows this structure based on the user's request.
-=================
+Your job is to create the STORY and TAXONOMY of the data, not recreate what the system already provides automatically.
+
+--------------
 
+Generate a complete JSON dungeon based on the user's request. Start with { and end with }. Nothing else.

package/lib/templates/schema.d.ts

@@ -0,0 +1,173 @@
+/**
+ * A "ValueValid" can be:
+ * - A primitive value (string, number, boolean)
+ * - An array of primitives (the system picks one randomly)
+ * - A function call object: { "functionName": "...", "args": [...] }
+ * - An arrow function object: { "functionName": "arrow", "body": "..." }
+ *
+ * This is the building block for all property values in the dungeon.
+ */
+type Primitives = string | number | boolean;
+type FunctionCall = { functionName: string; args?: any[]; body?: string };
+type ValueValid = Primitives | Primitives[] | FunctionCall;
+
+
+/**
+ * The main configuration object for the entire data generation spec, known as a "Dungeon".
+ * This is the high-level object you will be constructing.
+ *
+ * REQUIRED fields: events, funnels, superProps, userProps
+ * OPTIONAL fields: scdProps, groupKeys, groupProps, groupEvents
+ */
+export interface Dungeon {
+    /** REQUIRED: A list of all possible events that can occur in the simulation. */
+    events: EventConfig[];
+
+    /** REQUIRED: A list of event sequences that represent user journeys (e.g., sign-up, purchase). */
+    funnels: Funnel[];
+
+    /** REQUIRED: Properties that are attached to every event for all users. */
+    superProps: Record<string, ValueValid>;
+
+    /** REQUIRED: Properties that define the characteristics of individual users. */
+    userProps: Record<string, ValueValid>;
+
+    /** OPTIONAL: Properties that change for users or groups over time (Slowly Changing Dimensions). Only include when properties explicitly change over time. */
+    scdProps?: Record<string, SCDProp>;
+
+    /** OPTIONAL: Defines group entities (companies, teams). Format: [["group_key", count], ...]. ONLY for B2B/SaaS scenarios. */
+    groupKeys?: [string, number][];
+
+    /** OPTIONAL: Properties for groups defined in groupKeys. ONLY include if groupKeys is defined. */
+    groupProps?: Record<string, Record<string, ValueValid>>;
+
+    /** OPTIONAL: Events attributed to groups on a schedule (e.g., monthly billing). Rarely needed. */
+    groupEvents?: GroupEventConfig[];
+}
+
+
+/**
+ * Defines a single event, its properties, and its likelihood of occurring.
+ *
+ * The "weight" determines relative frequency - an event with weight 10 occurs
+ * roughly 10x more often than an event with weight 1.
+ */
+interface EventConfig {
+    /** REQUIRED: The name of the event (e.g., "Page View", "Add to Cart", "checkout"). */
+    event: string;
+
+    /** OPTIONAL: The relative frequency of this event. Higher numbers = more frequent. Default: 1 */
+    weight?: number;
+
+    /** OPTIONAL: Properties associated with this event. Each property can be a value or array. */
+    properties?: Record<string, ValueValid>;
+
+    /** OPTIONAL: If true, this event will be the first event for a new user (e.g., "sign up"). Only one event should have this. */
+    isFirstEvent?: boolean;
+
+    /** OPTIONAL: If true, this event signifies that a user has churned (e.g., "account deleted"). */
+    isChurnEvent?: boolean;
+}
+
+
+/**
+ * Defines a sequence of events that represents a meaningful user journey or workflow.
+ *
+ * Funnels model how users progress through your product - from sign-up to purchase,
+ * from onboarding to activation, etc. The conversionRate determines what percentage
+ * of users who start the funnel will complete it.
+ */
+interface Funnel {
+    /** REQUIRED: Event names that make up this journey. Must match event names in the events array. */
+    sequence: string[];
+
+    /** REQUIRED: Percentage (0-100) of users who complete the funnel. 15 means 15% conversion. */
+    conversionRate: number;
+
+    /** OPTIONAL: The name of the funnel (e.g., "Purchase Funnel", "Onboarding Flow"). */
+    name?: string;
+
+    /** OPTIONAL: The likelihood that a user will attempt this funnel vs others. Default: 1 */
+    weight?: number;
+
+    /** OPTIONAL: If true, this is an initial user experience funnel (e.g., onboarding). */
+    isFirstFunnel?: boolean;
+
+    /** OPTIONAL: Average hours to complete the funnel. Default: 1 */
+    timeToConvert?: number;
+
+    /**
+     * OPTIONAL: How events are ordered within the funnel.
+     * - "sequential" (default): Events happen in exact order
+     * - "random": Events can happen in any order
+     * - "first-fixed": First event is fixed, rest are random
+     * - "last-fixed": Last event is fixed, rest are random
+     * - "first-and-last-fixed": First and last are fixed, middle is random
+     */
+    order?: "sequential" | "random" | "first-fixed" | "last-fixed" | "first-and-last-fixed";
+
+    /** OPTIONAL: Properties attached to every event in this funnel (e.g., experiment_variant, traffic_source). */
+    props?: Record<string, ValueValid>;
+
+    /** OPTIONAL: User property conditions for eligibility. Only users matching these values run this funnel. */
+    conditions?: Record<string, ValueValid>;
+
+    /** OPTIONAL: If true, generates 3 variants with different conversion rates for A/B testing analysis. */
+    experiment?: boolean;
+}
+
+
+/**
+ * Defines a "Slowly Changing Dimension" - a property of a user or group
+ * that changes periodically over time (e.g., subscription plan, user role).
+ *
+ * ONLY include SCDs when properties explicitly need to change over time.
+ * For static properties, just use userProps or groupProps.
+ */
+interface SCDProp {
+    /** OPTIONAL: The entity type - 'user' or a group key like 'company_id'. Default: 'user' */
+    type?: "user" | string;
+
+    /** REQUIRED: How often this property can change. */
+    frequency: "day" | "week" | "month" | "year";
+
+    /** REQUIRED: Possible values for this property. */
+    values: ValueValid;
+
+    /**
+     * REQUIRED: When changes occur.
+     * - "fixed": Changes occur exactly on the frequency interval
+     * - "fuzzy": Changes occur randomly around the interval
+     */
+    timing: "fixed" | "fuzzy";
+
+    /** OPTIONAL: Maximum number of times this property can change per entity. Default: 100 */
+    max?: number;
+}
+
+
+/**
+ * Defines an event attributed to a group on a regular schedule.
+ * Example: monthly subscription charges, weekly reports, etc.
+ *
+ * This is rarely needed - only use for B2B scenarios with recurring group-level events.
+ */
+interface GroupEventConfig {
+    /** REQUIRED: The name of the event. */
+    event: string;
+
+    /** REQUIRED: How often the event occurs (in days). e.g., 30 for monthly. */
+    frequency: number;
+
+    /** REQUIRED: The group key this event belongs to (e.g., "company_id"). */
+    group_key: string;
+
+    /** OPTIONAL: If true, a random user in the group is also attributed to the event. */
+    attribute_to_user?: boolean;
+
+    /** OPTIONAL: Properties for this event. */
+    properties?: Record<string, ValueValid>;
+
+    /** OPTIONAL: Relative frequency of this event. */
+    weight?: number;
+}