Interpreter Engine (Claude AI)

Relevant source files

The following files were used as context for generating this wiki page:

• src/engine/interpreter.ts
• README.md
• plan.md
• src/test-validation.ts
• src/test-smoke.ts

The Interpreter Engine is the first stage of the Abee (SynthCrowd) synthetic testing pipeline. Its primary purpose is to transform raw, unstructured user input—such as a natural language description of a customer or a website URL—into a structured PersonaConfig object. This configuration serves as the statistical center-point for the subsequent generation of a diverse population of AI browser agents.

The engine leverages the Claude 3.5 Sonnet LLM (claude-sonnet-4-20250514) to perform deep reasoning on input data. It is designed to "infer aggressively," meaning it uses contextual clues to fill in gaps in a persona's traits (e.g., assuming high income and low patience for a "busy executive") rather than defaulting to neutral values.

Sources: README.md:27-38, src/engine/interpreter.ts:7-40, plan.md:14-16

Architecture and Data Flow

The Interpreter Engine handles two types of input: natural language descriptions and website URLs. If a URL is provided, the engine first fetches the page, strips HTML, and generates a summary of the site's target audience before proceeding to structured trait extraction.

The diagram shows the logic path from raw input to the final structured PersonaConfig used by the rest of the pipeline. Sources: src/engine/interpreter.ts:42-125, README.md:27-44

Input Processing Logic

1. URL Detection: The engine checks if the input is a valid URL using the isUrl helper.
2. Web Content Extraction: If a URL is detected, the fetchAndSummarize function retrieves the HTML, removes <script> and <style> tags, and caps the text content to 8,000 characters to fit LLM token limits.
3. Audience Summarization: Claude analyzes the extracted text to describe the Ideal Customer Profile (ICP) demographics, goals, and buying behaviors.
4. Trait Extraction: The final description (either the original NL input or the generated summary) is sent to Claude with a strict system prompt to produce a JSON object matching the 19-trait schema.

Sources: src/engine/interpreter.ts:42-81, src/engine/interpreter.ts:133-145

Structured Persona Model

The engine is responsible for populating 19 specific traits across five categories. All numeric traits are normalized to a 0-1 scale to facilitate Gaussian variation in the later population generation stage.

Persona Trait Schema

Category	Trait	Type	Description
Demographics	age, gender, location, income_bracket, education	Misc	Core identity markers (Age: 18-90).
Digital	tech_literacy, patience, attention_span, device_preference	0-1 / Enum	Controls technical capability and friction tolerance.
Context	domain_familiarity, goal_clarity, purchase_intent, price_sensitivity	0-1	Defines the user's relationship with the product/goal.
Language	english_proficiency, primary_language	0-1 / String	Affects reading comprehension and error message handling.
Behavioral	decision_style, jargon_tolerance, form_tolerance, trust_baseline	Enum / 0-1	Defines browsing style (e.g., impulsive vs. methodical).

Sources: src/engine/interpreter.ts:15-38, README.md:104-142

Validation and Defaults

After Claude generates the JSON, the engine passes the data through validateAndFillDefaults. This function ensures all numeric values are clamped within their valid ranges (0-1 or 18-90) and that enums match predefined allowed values.

function validateAndFillDefaults(raw: Record<string, unknown>): PersonaConfig {
  const clamp = (v: unknown, min: number, max: number): number => {
    const n = Number(v);
    if (isNaN(n)) return (min + max) / 2;
    return Math.min(max, Math.max(min, n));
  };
  // ... validation for enums and strings
}

Sources: src/engine/interpreter.ts:83-131

Testing and Verification

The Interpreter Engine's performance is verified through validation suites that compare how different inputs result in distinct persona configurations. For instance, comparing "Grandma in Ohio" against "SF Tech Bro" demonstrates the engine's ability to differentiate traits like tech_literacy and patience.

The sequence shows how the engine maintains contrast between diverse ICP inputs during validation. Sources: src/test-validation.ts:10-55, src/test-smoke.ts:31-36

Conclusion

The Interpreter Engine (Claude AI) serves as the foundational intelligence layer for the Abee platform. By converting qualitative customer descriptions into quantitative trait models, it enables the system to generate statistically diverse populations that accurately reflect the nuances of a target audience. Its ability to summarize website content and infer missing data points allows it to function even with minimal user input.

Sources: README.md:39-44, plan.md:14-16