Country-Calibrated Persona Populations for an Agent Simulation Platform

Overview

A working fork of MatrAIx, an open-source, population-scale platform that instantiates sampled persona records as LLM agents and runs them through reproducible Survey, AI Chatbot, Web, and native-app tasks. On top of the upstream framework we added a Romania-calibrated persona pipeline, a self-service “Survey Studio” front end, a remote MCP server, and a Terraform-managed cloud deployment so the simulator could be used for real market-research style runs.

Why It Exists

Testing products and AI systems against a single generic user hides how heterogeneous real audiences are. MatrAIx addresses this with a shared schema of 1,290 categorical persona dimensions and a public one-million-persona coreset, but the released population is global. We needed a locally grounded population and a non-technical way to design, run, and read surveys against it, without rewriting the evaluation engine.

What We Built

Working against the upstream MatrAIx-ai/MatrAIx-Persona-8B repository (MIT) from our own fork, we kept the Playground backend (FastAPI) as the engine and extended around it:

• Romania-calibrated persona pipeline (persona/romania/): scripts to fetch Eurostat indicators, parse national census tables (age by geography, education, occupation, marital status, ethnicity, religion, mother tongue, tenure, family nuclei), derive a joint ro_targets.json, finalize and validate a country-specific pool. The commit describes a 2,000-persona pool; the upstream persona_generator was adjusted to consume these targets.
• Survey Studio (apps/showcase/): a Next.js 16 / React 19 / Tailwind 4 app for creating a survey manually or with a chat assistant, picking an audience from any persona pool, launching a run, and reading aggregated results via the backend’s /api/studio/*, /api/persona-pool/*, and /api/harbor/jobs/* routes.
• Remote MCP server (application/playground/mcp/): exposes the simulator to Claude, ChatGPT, and Claude Code as a connector, acting as its own OAuth 2.1 authorization server with dynamic client registration, PKCE, and refresh tokens.
• Infrastructure (infra/sim/): Terraform for a Hetzner Cloud server, volume, firewall, Cloudflare Tunnel and DNS, plus a deploy.sh release step and systemd units for backend, studio, and MCP; inbound is SSH-only with all HTTP via the tunnel.
• Jobs and configs: YAML job recipes under configs/jobs/, a DeepSeek gateway test, and a series of Romanian-market survey runs recorded under jobs/.

We also tracked upstream closely while it added Modal/GKE compute families, additional persona model providers, and Playground cohort/overlay features.

Technologies & Approach

Python 3.12 managed with uv; the matraix package (Typer CLI, Pydantic, FastAPI/uvicorn) with LiteLLM for provider-agnostic model routing and the Claude Agent SDK for agent runs. Web and OS-app tasks execute in Docker task environments driven by Playwright, browser-use, or computer-use agents; verifiers and LLM-judge checks live in the rewardkit package. Frontends are React (Playground, Vite) and Next.js (Studio). Deployment is fully declarative via Terraform with Hetzner and Cloudflare providers, chosen so a single modest box can host backend, studio, and MCP without opening public ports.

Outcome / Impact

Turned a research framework into a usable, hosted survey simulator with a locally grounded population: non-technical users can author and run surveys from a browser, and agent clients can drive the same engine over MCP. The country-calibration pipeline is reusable for other markets given equivalent census and Eurostat inputs. Work is ongoing; the platform’s own positioning applies, simulated respondents support exploration and hypothesis generation, not a replacement for evidence from real people.

Capabilities Demonstrated

• Extending a large open-source LLM-agent codebase without forking the core engine
• Building statistically targeted synthetic populations from census and Eurostat data
• Shipping self-service AI tooling (Next.js) on top of a FastAPI evaluation backend
• Exposing an internal AI service to Claude/ChatGPT via an OAuth-secured MCP server
• Infrastructure-as-code for AI workloads: Terraform, Hetzner, Cloudflare Tunnel, systemd
• Multi-provider LLM orchestration (Anthropic, OpenAI, DeepSeek, Gemini, and others via LiteLLM)