Prompt Compiler
Relevant source files
The following files were used as context for generating this wiki page:
The Prompt Compiler is a core component of the SynthCrowd engine responsible for transforming structured PersonaConfig data into fully realized, natural-language identities and deterministic behavioral rules. It serves as Stage 3 in the synthetic testing pipeline, bridging the gap between statistical population generation and autonomous browser agent execution.
By mapping numeric traits (e.g., tech literacy, patience) to specific textual instructions, the Prompt Compiler ensures that AI agents navigate websites with human-like limitations, preferences, and emotional reactions. This transformation allows the system to simulate diverse user journeys, from a "tech-savvy engineer" to a "non-technical elderly user," ensuring high fidelity in synthetic user testing.
Sources: src/engine/promptCompiler.ts, README.md:88-91, plan.md:112-116
Architecture and Data Flow
The Prompt Compiler operates by aggregating outputs from two primary sub-modules: the Identity Generator and the Behavioral Rule Engine. It takes a PersonaConfig, a target URL, and a conversion goal as input, producing a CompiledPersona object.
The diagram shows the flow from structured configuration traits to the final concatenated system prompt used by browser agents.
Sources: src/engine/promptCompiler.ts:359-400, README.md:46-56
Identity Prompt Generation
The generateIdentityPrompt function constructs a natural-language paragraph describing who the persona is. It uses descriptors for age, tech savviness, income, education, and language ability to create a cohesive backstory.
- Age Descriptors: Categorizes users into groups such as "young," "middle-aged," "older," or "elderly."
- Tech Literacy: Maps values to descriptions ranging from "rarely uses computers" to "very tech-savvy."
- Contextual Inference: Combines demographic traits with domain familiarity to set the stage for the agent's mindset.
Sources: src/engine/promptCompiler.ts:311-355, README.md:109-111
Behavioral Rule Engine
The Behavioral Rule Engine is a deterministic mapping system. Unlike LLM-generated personas, these rules are hardcoded based on trait value ranges (0-1) to ensure consistency and prevent "personality drift."
Trait-to-Rule Mapping
The compiler evaluates 13 different trait categories to select appropriate rules. A typical persona accumulates between 15 and 35 specific rules.
| Trait Category | Logic Example | Sample Behavioral Rule |
|---|---|---|
| Tech Literacy | level < 0.2 | "You do NOT understand hamburger menus (☰)." |
| Patience | level < 0.2 | "If a page takes > 3 seconds... you leave." |
| Trust Baseline | level < 0.3 | "You are suspicious of this website by default." |
| Language | proficiency < 0.3 | "Error messages in English are incomprehensible." |
| Decision Style | cautious | "You proceed slowly and look for reasons NOT to proceed." |
Sources: src/engine/promptCompiler.ts:6-267, README.md:95-107, src/test-validation.ts:74-85
Rule Tagging and Selection
The compiler uses a TaggedRule structure to track the "extremity" of a trait, calculated as Math.abs(traitValue - 0.5). This allows the system to identify the most defining characteristics of a persona. In optimization loops, these extremities can be used for smart rule selection.
export interface TaggedRule {
rule: string;
trait: string;
extremity: number; // Higher = more defining
}
Sources: src/engine/promptCompiler.ts:365-376, plan.md:143-146
Integration in Optimization Loop
The Prompt Compiler is invoked in every iteration of the runOptimizationLoop. While the underlying PersonaConfig remains the same across iterations to maintain consistency, the prompts are re-compiled to ensure the agents remain grounded in the latest goal and target URL parameters.
The sequence demonstrates how the Prompt Compiler provides the necessary instructions for the Parallel Runner to execute agent sessions.
Sources: src/engine/optimizationLoop.ts:167-170, src/test-demo-site.ts:66-72
Technical Implementation Details
Key Functions
compilePersona(config, targetUrl, goal): The primary entry point. Orchestrates the generation of identity and behavioral rules into a finalsystem_prompt.compilePopulation(personas, targetUrl, goal): A utility function that mapscompilePersonaover an array of configurations.ageBasedRules(age): Specific logic for age-related UX limitations, such as difficulty reading small text for users over 65.
Navigation Instructions
The compiler appends a standard set of navigation instructions to every prompt, mandating that the agent:
- Narrate an internal monologue.
- Express confusion or frustration explicitly.
- Fill forms with realistic fake data.
- Explain abandonment or success in character.
Sources: src/engine/promptCompiler.ts:381-432, README.md:113-118
Summary
The Prompt Compiler acts as the translation layer of SynthCrowd, converting raw statistics into actionable AI behavior. By utilizing a deterministic rule engine combined with natural-language identity generation, it provides the necessary constraints for browser agents to accurately simulate the friction points of real-world user cohorts. This system is critical for generating the "Internal Monologue" data used later by the Report Generator to identify site failures.
Sources: README.md:13-26, src/engine/reportGenerator.ts:65-75