MatrAIx

Simulate before reality.

Infraestrutura em escala populacional e orientada a personas para avaliar sistemas de IA e produtos interativos com usuários simulados heterogêneos.

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

Website Discord X LinkedIn Google Form Docs Hugging Face License Playground

Assista à demo do MatrAIx no YouTube

Assista à demo do MatrAIx no YouTube

--- **MatrAIx** é uma infraestrutura em escala populacional e orientada a personas para avaliar sistemas de IA e produtos interativos com usuários simulados heterogêneos. Em vez de testar contra um usuário genérico ou intercambiável, o MatrAIx instancia registros de persona amostrados como agentes LLM e os executa em tarefas reproduzíveis em quatro ambientes — **Survey**, **AI Chatbot**, **Web** e **App** (desktop e mobile nativos, incluindo macOS e iOS). Na base há um schema compartilhado de **1.290 dimensões categóricas** que cobrem histórico, psicologia, capacidade e comportamento. As personas combinam geração sintética sensível a dependências com grounding humano baseado em evidências; um coreset determinístico e filtrado por qualidade de **um milhão de personas** é publicado para pesquisa no [Hugging Face](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release). Telemetria compartilhada, verificação própria de cada tarefa e relatórios conectam respostas e trajetórias individuais a achados em nível de subgrupo e população. O nome remete a *The Matrix*: um mundo simulado útil para exploração, testes de estresse e geração de hipóteses — **não um substituto para evidências de pessoas reais**. ## Novidades & reconhecimento - **Comentário acadêmico** — [*Can We Simulate the World?*](https://aiscientist.substack.com/p/can-we-simulate-the-world) — Mayank Kejriwal ([*AI Scientist*](https://aiscientist.substack.com/)) - **Seleção de pesquisa** — Destaque no [Hugging Face Papers](https://huggingface.co/papers/2608.04205) ([Papers do dia, 2026-08-10](https://huggingface.co/papers/date/2026-08-10)) - **Mídia** — [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 Times](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 Turquia](https://www.forbes.com.tr/saglik/hastaya-dokunmadan-once-8-3-milyar-kez-denemek-sagligin-yeni-test-dunyasi-matraix) · [WIRED Tchéquia](https://www.wired.cz/news-beat/harvard-a-mit-vytvorily-ai-simulaci-obsahujici-83-miliardy-virtualnich-lidi) - **Comentário da indústria** — Discutido pelo vice-presidente e CTO da Cisco [Gianpaolo Barozzi](https://lnkd.in/p/gE9cV2nw) - **Redes** — Destaque como [história em tendência no X](https://x.com/i/trending/2086626337561911419) ## Lançamentos - **[2026-08-04]** Relatório técnico no arXiv: [MatrAIx: Simulating the World with 8.3 Billion Persona Agents](https://arxiv.org/abs/2608.04205) (`2608.04205`). - **[2026-08-01]** Publicado o [Persona 1M](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release) no Hugging Face (~1M personas filtradas por qualidade). - **[2026-07-31]** Playground e biblioteca de tarefas em código aberto: [MatrAIx-Persona-8B](https://github.com/MatrAIx-ai/MatrAIx-Persona-8B). - **[2026-07-29]** Nota de posição: [From Personas to Simulated Users](https://matraix.ai/research/survey-from-personas-to-simulated-users.html). ## Requisitos - [Docker](https://docs.docker.com/get-docker/) - [uv](https://docs.astral.sh/uv/) e Python 3.12 - Node.js 20+ (apenas frontends do Playground / viewer) - Chaves de API de modelo para exemplos de agentes de persona — veja [agents.md](../environment/agents.md) > **Usuários de Windows**: execute tudo dentro do > [WSL2](https://learn.microsoft.com/windows/wsl/install) — abra o PowerShell, > execute `wsl --install` (instala o Ubuntu), depois clone este repositório > **dentro do sistema de arquivos do WSL** (ex.: `~/MatrAIx`, não `/mnt/c/…`, > que é muito mais lento) e ative a *WSL integration* em Docker Desktop → > Settings → Resources. A partir daí, todos os comandos deste README funcionam > exatamente como estão. PowerShell/cmd nativo não é suportado (os > verificadores de tarefas exigem `bash`). ## Instalação ```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 ``` Execute jobs e tarefas com **`uv run matraix run …`**: ele configura o ambiente de lançamento completo e delega ao runtime Harbor. As utilidades do runtime (ex.: `harbor view`, `harbor upload`) continuam em **`uv run harbor …`**. Defina a chave de API do modelo correspondente ao seu provedor antes de executar tarefas via GUI ou CLI (o teste de fumaça não precisa de chave): ```bash export ANTHROPIC_API_KEY="sk-ant-..." # modelos anthropic/claude-* # export OPENAI_API_KEY="sk-..." # modelos openai/gpt-* ``` Veja a matriz completa de chaves em [agents.md](../environment/agents.md). O Playground também pode carregar chaves de `application/playground/.env.local`. ### Importar Persona 1M (recomendado) O `matraix-persona-dev-sample` do repo (~200) destina-se apenas a testes de fumaça. Para coortes reais e amostragem no Playground, importe o 1M público: ```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`. Detalhes: [Handbook § Persona 1M](../README.md#3-persona-1m-recommended). ## Início rápido ### Testes de fumaça (smoke tests) Após instalar, rode estas duas verificações (sem chave de API). Juntas elas confirmam o caminho padrão de Survey, Chat, Web e OS-app: | Verificação | Confirma que você pode rodar | Comando | |-------------|------------------------------|---------| | **Sem Docker** | Survey e Chat | `uv run matraix smoke application/tasks/example-survey_product-feedback` | | **Com Docker** | Web e OS-app | `uv run matraix run -c configs/jobs/example-job-recipe/harbor-smoke-local.yaml` | A primeira costuma terminar em segundos com `Smoke: ok`. A segunda constrói uma imagem local na primeira execução (alguns minutos) e grava em `jobs/harbor-smoke-local/`. Passos: [quickstart §3](../quickstart.md#3-smoke-tests-two-lanes). ### Execuções de tarefa via GUI O Playground escolhe tarefas, amostra personas e lança os mesmos jobs do Matraix Playground que o modo auto da CLI. Inicie API + frontend (dois terminais): ```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 ``` Abra **http://localhost:5173** → Playground → escolha uma coorte de personas → escolha tarefas Survey / Chat / Web / OS app → **Lock pipeline** → **Run eval**. Detalhes: [Playground §10](../quickstart.md#10-playground--play-tasks-visually). ### Desenvolvimento / execução via CLI **Desenvolver** — copie uma tarefa de referência em `application/tasks/`, edite `task.toml` / `instruction.md` / `input/` / o verificador (verifier) e registre-a no Playground ([task-guide.md](../application/task-guide.md)): ```bash cp -R application/tasks/example-survey_product-feedback \ application/tasks/ ``` | Tipo | Tarefa de referência | |------|----------------------| | 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` | **Executar** — gere um job do Matraix Playground (fixa agent + model) e execute-o: ```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 as linhas de export + o caminho do recipe impressos pelo script, p.ex.: uv run matraix run -c configs/jobs/application-task-job-recipe/example-survey-product-feedback-auto-n1.yaml ``` Lote (`--sample-size N`), filtros e exemplos chat / web / os-app: [docs/quickstart.md](../quickstart.md). ## Docs **[MatrAIx Handbook](../README.md)** — guias e docs de persona / application / environment.

Arquitetura MatrAIx

## Estrutura do repositório ```text MatrAIx/ ├── persona/ Schema, datasets, pipelines de síntese/curadoria/validação │ ├── schema/ Schema de persona com 1.290 dimensões │ ├── datasets/ Pool de amostras de dev e YAMLs de persona │ ├── validation/ Suites de grounding / validação de qualidade │ └── scripts/ Helpers de job e pipeline de persona ├── application/ │ ├── tasks/ Specs de tarefas Survey · chat · web · os-app │ ├── task-spec/ Contratos compartilhados de tarefa │ ├── playground/ Runner visual (API backend + frontend) │ └── scripts/ generate_application_job.py e tooling de tarefas ├── environment/ │ ├── runtime/ Runtime do Matraix Playground │ ├── agents/ Agentes condicionados a persona │ ├── task-environments/ Imagens Docker / sidecars │ └── adapters/ Adaptadores externos (ex.: SimpleQA) ├── packages/ playground · rewardkit · harbor-langsmith ├── apps/viewer/ Frontend pareado com `harbor view` ├── configs/jobs/ Recipes de job do Matraix Playground (curados e gerados) ├── docs/ Handbook — persona/ · application/ · environment/ ├── examples/ Tarefas de exemplo mínimas ├── src/matraix/ Entry points do pacote Python ├── scripts/ Helpers no nível do repositório ├── tests/ Testes unitários / de ambiente └── jobs/ Saídas locais do Matraix Playground (gitignored) ``` Datasets grandes gerados ficam fora do git (veja o release no Hugging Face acima). ## Participe da comunidade [![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. Entre no Discord — nickname **`Full Name - Affiliation`**. Preencha o Google Form (histórico, interesses, autoria / agradecimentos em papers). 2. Diga oi! Gostamos de conectar pessoas com interesses ou experiências em comum! 3. Participe da comunidade de pesquisa MatrAIx para colaboração ou contribuição! ## Citação Se você usar MatrAIx, o dataset Persona 1M ou resultados deste repositório, 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} } ``` Artigo: [arXiv:2608.04205](https://arxiv.org/abs/2608.04205) · Autores completos: 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 ## Licença MIT — veja [LICENSE](../../LICENSE).