MatrAIx

Simulate before reality.

Population-scale, persona-driven infrastructure for evaluating AI systems and interactive products with heterogeneous simulated users.

English | 简体中文 | 繁體中文 | 한국어 | 日本語 | Español | Português

Website Discord X LinkedIn Google Form Docs Hugging Face License Playground

Watch the MatrAIx demo on YouTube

Watch the MatrAIx demo on YouTube

--- **MatrAIx** is a population-scale, persona-driven infrastructure for evaluating AI systems and interactive products with heterogeneous simulated users. Instead of testing against a generic or interchangeable user, MatrAIx instantiates sampled persona records as LLM agents and runs them through reproducible tasks across four environments — **Survey**, **AI Chatbot**, **Web**, and **App** (native desktop and mobile, including macOS and iOS). At its foundation is a shared schema of **1,290 categorical dimensions** covering background, psychology, capability, and behavior. Personas combine dependency-aware synthetic generation with evidence-aware human grounding; a deterministic, quality-filtered coreset of **one million personas** is released for research on [Hugging Face](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release). Shared telemetry, task-owned verification, and reporting connect individual responses and trajectories to subgroup- and population-level findings. The name nods to *The Matrix*: a simulated world useful for exploration, stress testing, and hypothesis generation, **not a replacement for evidence from real people**. ## News & Recognition - **Academic commentary** — [*Can We Simulate the World?*](https://aiscientist.substack.com/p/can-we-simulate-the-world) — Mayank Kejriwal, [*AI Scientist*](https://aiscientist.substack.com/) - **Research selection** — Featured on [Hugging Face Papers](https://huggingface.co/papers/2608.04205) ([Daily Papers, 2026-08-10](https://huggingface.co/papers/date/2026-08-10)) - **Media** — [Forbes](https://www.forbes.com/sites/lanceeliot/2026/08/26/using-eight-billion-ai-personas-for-psychology-research-has-its-ups-and-downs/) · [NZZ am Sonntag](https://www.nzz.ch/nzz-am-sonntag/report-und-debatte/die-ki-vermessung-der-menschheit-unsere-acht-milliarden-doppelgaenger-ld.10019342) · [AI Era (via 36Kr)](https://www.36kr.com/p/3932853833759876) · [Numerama](https://www.numerama.com/tech/2308727-ces-chercheurs-ont-cree-83-milliards-dhumains-virtuels-pour-tester-des-produits-a-notre-place.html) · [Infobae](https://www.infobae.com/tecno/2026/08/10/asi-prueba-la-ia-un-mundo-con-8300-millones-de-personas-digitales-matraix-es-el-metaverso/) · [HispanicAd](https://hispanicad.com/news/harvard-and-mit-built-8-3-billion-ai-personas-to-simulate-the-world-report/) · [AI타임스](https://www.aitimes.com/news/articleView.html?idxno=213824) · [Startup Fortune](https://startupfortune.com/harvard-and-mit-built-an-ai-model-of-83-billion-people-to-test-products-on/) · [Forbes Türkiye](https://www.forbes.com.tr/saglik/hastaya-dokunmadan-once-8-3-milyar-kez-denemek-sagligin-yeni-test-dunyasi-matraix) · [WIRED Czech](https://www.wired.cz/news-beat/harvard-a-mit-vytvorily-ai-simulaci-obsahujici-83-miliardy-virtualnich-lidi) - **Industry commentary** — Discussed by Cisco VP & CTO [Gianpaolo Barozzi](https://lnkd.in/p/gE9cV2nw) - **Social** — Featured as an [X Trending Story](https://x.com/i/trending/2086626337561911419) ## Releases - **[2026-08-04]** Technical report on arXiv: [MatrAIx: Simulating the World with 8.3 Billion Persona Agents](https://arxiv.org/abs/2608.04205) (`2608.04205`). - **[2026-08-01]** Released [Persona 1M](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release) on Hugging Face (~1M quality-filtered personas). - **[2026-07-31]** Open-sourced the Playground and task library: [MatrAIx-Persona-8B](https://github.com/MatrAIx-ai/MatrAIx-Persona-8B). - **[2026-07-29]** Position note: [From Personas to Simulated Users](https://matraix.ai/research/survey-from-personas-to-simulated-users.html). ## Requirements - [Docker](https://docs.docker.com/get-docker/) — needed for Web and OS-app tasks - [uv](https://docs.astral.sh/uv/) and Python 3.12 - Node.js 20+ (Playground / viewer frontends only) - Model API keys for real persona runs — see [agents.md](docs/environment/agents.md) (the install checks below do not need a key) > **Windows users**: run everything inside > [WSL2](https://learn.microsoft.com/windows/wsl/install) — open PowerShell, > run `wsl --install` (installs Ubuntu), then clone this repo **inside the WSL > filesystem** (e.g. `~/MatrAIx`, not `/mnt/c/…`, which is much slower) and > enable *WSL integration* in Docker Desktop → Settings → Resources. Every > command in this README then works exactly as written. Native > PowerShell/cmd is not supported (the task verifiers require `bash`). ## Installation ```bash git clone && cd MatrAIx uv venv --python 3.12 uv pip install -e . uv pip install pytest pytest-asyncio httpx uv pip install -e packages/playground uv pip install -e packages/harbor-langsmith uv pip install -e packages/rewardkit ``` Run jobs with **`uv run matraix run …`**. After install, use the [smoke tests](#smoke-tests) below to confirm Survey, Chat, Web, and OS-app are ready (no API key). Summarize a finished job with **`uv run matraix results `**. Advanced runtime tools stay under `uv run harbor …`. Set a model API key before real GUI or CLI runs (smoke checks do not need one): ```bash export ANTHROPIC_API_KEY="sk-ant-..." # anthropic/claude-* models # export OPENAI_API_KEY="sk-..." # openai/gpt-* models ``` See [agents.md](docs/environment/agents.md) for the full key matrix. Playground can also load keys from `application/playground/.env.local`. ### Import Persona 1M (recommended) The in-repo `matraix-persona-dev-sample` (~200) is for smoke only. For real cohorts and Playground sampling, import the public 1M coreset: ```bash huggingface-cli download MatrAIx2026/MatrAIx_Persona_1M_Public_Release \ --repo-type dataset \ --local-dir persona/datasets/matraix-persona-1m/release ``` Playground: Dataset → **`matraix-persona-1m`**. CLI: `--dataset persona/datasets/matraix-persona-1m`. Details: [Handbook § Persona 1M](docs/README.md#3-persona-1m-recommended). ## Quick start ### Smoke tests Two quick checks after install — no API key. Together they cover the default path for all four task types (Survey, Chat, Web, OS-app): | Check | Confirms you can run | Command | |-------|----------------------|---------| | **Without Docker** | Survey and Chat | `uv run matraix smoke application/tasks/example-survey_product-feedback` | | **With Docker** | Web and OS-app | `uv run matraix run -c configs/jobs/example-job-recipe/harbor-smoke-local.yaml` | The first finishes in seconds and should print `Smoke: ok`. The second builds a small local image on first run (a few minutes), then writes under `jobs/harbor-smoke-local/`. Step-by-step: [quickstart §3](docs/quickstart.md#3-smoke-tests-two-lanes). ### GUI task runs Playground picks tasks, samples personas, and launches the same Matraix Playground jobs as CLI auto mode. Start API + frontend (two terminals): ```bash # Terminal A — API VENV=.venv bash application/playground/backend/run_dev.sh # Terminal B — frontend cd application/playground/frontend && npm ci && npm run dev ``` Open **http://localhost:5173** → Playground → pick a persona cohort → pick Survey / Chat / Web / OS app tasks → **Lock pipeline** → **Run eval**. Details: [Playground §10](docs/quickstart.md#10-playground--play-tasks-visually). ### CLI task develop / runs **Develop** — copy a reference task under `application/tasks/`, edit `task.toml` / `instruction.md` / `input/` / verifier, then register it for Playground ([task-guide.md](docs/application/task-guide.md)): ```bash cp -R application/tasks/example-survey_product-feedback \ application/tasks/ ``` | Type | Reference task | |------|----------------| | Survey | `application/tasks/example-survey_product-feedback` | | Chat | `application/tasks/example-chat-api_support_chatbot` | | Web | `application/tasks/example-web-playwright_quote-choice` | | OS-app | `application/tasks/example-computer-use-linux_note-to-csv` | **Run** — generate a Matraix Playground job (pins agent + model), then execute it: ```bash uv run python application/scripts/generate_application_job.py \ --task application/tasks/example-survey_product-feedback \ --execution-mode auto \ --persona-ids 0042 \ --model-name anthropic/claude-sonnet-4-6 # Use the export lines + recipe path the script prints, e.g.: uv run matraix run -c configs/jobs/application-task-job-recipe/example-survey-product-feedback-auto-n1.yaml ``` Batch (`--sample-size N`), filters, and chat / web / os-app examples: [docs/quickstart.md](docs/quickstart.md). ## Docs **[MatrAIx Handbook](docs/README.md)** — guides, persona / application / environment docs.

MatrAIx architecture

## Repository layout ```text MatrAIx/ ├── persona/ Schema, datasets, synthesis/curation/validation pipelines │ ├── schema/ 1,290-dimension persona schema │ ├── datasets/ Dev sample pool and persona YAMLs │ ├── validation/ Grounding / quality validation suites │ └── scripts/ Persona job & pipeline helpers ├── application/ │ ├── tasks/ Survey · chat · web · os-app task specs │ ├── task-spec/ Shared task contracts │ ├── playground/ Visual runner (backend API + frontend) │ └── scripts/ generate_application_job.py and task tooling ├── environment/ │ ├── runtime/ Matraix Playground runtime │ ├── agents/ Persona-conditioned agents │ ├── task-environments/ Docker images / sidecars │ └── adapters/ External adapters (e.g. SimpleQA) ├── packages/ playground · rewardkit · harbor-langsmith ├── apps/viewer/ Frontend paired with `harbor view` ├── configs/jobs/ Curated & generated Matraix Playground job recipes ├── docs/ Handbook — persona/ · application/ · environment/ ├── examples/ Minimal example tasks ├── src/matraix/ Python package entrypoints ├── scripts/ Repo-level helpers ├── tests/ Unit / environment tests └── jobs/ Local Matraix Playground run outputs (gitignored) ``` Large generated datasets stay outside git (see the Hugging Face release above). ## Join the Community [![Discord](https://img.shields.io/badge/Discord-join%20MatrAIx-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/knVyQQnRFa) [![X](https://img.shields.io/badge/X-follow%20%40MatrAIx2026-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/MatrAIx2026) [![LinkedIn](https://img.shields.io/badge/LinkedIn-follow%20MatrAIx-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/matraix) [![Google Form](https://img.shields.io/badge/Google%20Form-join%20MatrAIx-4285F4?style=for-the-badge&logo=googleforms&logoColor=white)](https://forms.gle/hwEHng5HGWRqcJue9) 1. Join Discord — nickname **`Full Name - Affiliation`**. Fill the Google Form (background, interests, paper authorship / acknowledgements). 2. Say hi to us! We like to connect you for the shared interest or experience! 3. Participating MatrAIx research community for collaboration or contribution! ## Citation If you use MatrAIx, the Persona 1M dataset, or results from this repository, please cite: ```bibtex @article{li2026matraix, title = {MatrAIx: Simulating the World with 8.3 Billion Persona Agents}, author = {Li, Xiaomin and Hao, Yuexing and Hou, Jianheng and Huang, Jintao and Wen, Qianfeng and Huang, Shirley and Liu, Yifan and Liu, Xiaoyi and Fan, Yilan and Wang, Yijun and others}, year = {2026}, eprint = {2608.04205}, archivePrefix = {arXiv}, primaryClass = {cs.AI}, url = {https://arxiv.org/abs/2608.04205} } ``` Paper: [arXiv:2608.04205](https://arxiv.org/abs/2608.04205) · Full authors: GitHub **Cite this repository** (`CITATION.cff`) · Dataset: [Persona 1M on Hugging Face](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release). ## Star History Star History Chart ## License MIT — see [LICENSE](LICENSE).