Population Generator
Relevant source files
The following files were used as context for generating this wiki page:
The Population Generator is a core engine component responsible for creating a statistically diverse set of synthetic user personas based on a single "center-point" configuration. This module bridges the gap between a high-level Ideal Customer Profile (ICP) and the hundreds of individual agents required for large-scale synthetic user testing. By applying mathematical variance to persona traits, the generator ensures that the synthetic crowd represents both the average target user and critical edge-case outliers.
Sources: src/engine/population.ts, README.md:65-68
Architecture and Data Flow
The Population Generator functions as the second stage of the Abee pipeline. It receives a structured PersonaConfig from the Interpreter and outputs an array of PersonaConfig objects. These objects are later processed by the Prompt Compiler to generate actionable behavioral rules for autonomous agents.
The diagram shows the inputs (center config, variance, count) being processed through different variation logic to produce the final diverse population.
Sources: src/engine/population.ts:114-118, README.md:31-41
Mathematical Variation Logic
The generator uses statistical methods to ensure a realistic distribution of traits across the generated population.
Gaussian Numeric Variation
For numeric traits (normalized on a 0-1 scale), the engine employs the Box-Muller transform. This generates normally distributed random numbers around the center-point mean. The standard deviation is derived from the user-provided variance parameter, where a variance of 1 represents roughly ±20% of the trait's range as one standard deviation.
function gaussianRandom(mean: number, stdDev: number): number {
const u1 = Math.random();
const u2 = Math.random();
const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
return mean + z * stdDev;
}
Sources: src/engine/population.ts:7-12, src/engine/population.ts:24-29
Categorical Traits
Traits such as income_bracket, education, and device_preference are varied using a probability-based "flip" logic. If the variance is low, the generator strongly favors the center-point value. As variance increases, the probability of selecting an alternative option from pre-defined sets (e.g., GENDERS, LOCATIONS) increases.
| Trait Category | Options / Range | Variation Method |
|---|---|---|
| Numeric | 0.0 - 1.0 | Box-Muller (Gaussian) |
| Age | 18 - 90 | Clamped Gaussian |
| Income | low, medium, high, very_high | Categorical Randomization |
| Education | none, high_school, bachelors, masters, phd | Categorical Randomization |
| Style | impulsive, methodical, cautious, research_heavy | Categorical Randomization |
Sources: src/engine/population.ts:35-43, src/engine/population.ts:45-73
Outlier Generation
A critical feature of the generator is the deliberate creation of "outliers." By default, the bottom 15% of any generated population is subjected to double the configured variance (capped at 1.0). This ensures the population includes edge cases—such as low-tech users in a tech-savvy ICP—which are essential for identifying friction points that only occur at the extremes of an audience.
Sources: src/engine/population.ts:121-123, README.md:78-81, src/test-population.ts:39-40
Key Implementation Functions
generatePopulation
The primary entry point that iterates n times to construct the population array.
- Parameters:
center: PersonaConfig: The statistical anchor for the population.n: number: The total number of personas to generate.variance: number: A 0-1 float controlling the spread of traits.
- Returns:
PersonaConfig[](without rules or identity prompts).
Sources: src/engine/population.ts:114-118
Trait-Specific Variators
The engine uses specialized functions for different data types to ensure realistic distributions:
varyAge(center, variance): Returns a rounded integer between 18 and 90.varyLocation(center, variance): Randomly selects from a global list of 10 countries if the variance check fails.varyNumeric(center, variance, min, max): Handles the clamping and Gaussian application for 0-1 scale traits.
Sources: src/engine/population.ts:31-33, src/engine/population.ts:75-78, src/engine/population.ts:24-29
Usage in Pipeline
In the optimizationLoop.ts, the population is generated once at the start of a session and stored in MongoDB to ensure consistency across multiple test iterations. This allows the system to verify if code changes fixed friction for the exact same set of diverse users.
Summary
The Population Generator provides the statistical diversity required to move beyond "happy path" testing. By combining Gaussian distributions for numeric skills (like tech_literacy and patience) with randomized categorical traits and specific outlier logic, it creates a synthetic crowd that realistically mirrors the complexities of a real-world user base.