MatrAIx

Simulate before reality.

Infraestructura a escala poblacional y orientada a personas para evaluar sistemas de IA y productos interactivos con usuarios simulados heterogéneos.

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

Website Discord X LinkedIn Google Form Docs Hugging Face License Playground

Ver la demo de MatrAIx en YouTube

Ver la demo de MatrAIx en YouTube

--- **MatrAIx** es una infraestructura a escala poblacional y orientada a personas para evaluar sistemas de IA y productos interactivos con usuarios simulados heterogéneos. En lugar de probar contra un usuario genérico o intercambiable, MatrAIx instancia registros de persona muestreados como agentes LLM y los ejecuta en tareas reproducibles en cuatro entornos — **Survey**, **AI Chatbot**, **Web** y **App** (escritorio y móvil nativos, incluidos macOS e iOS). En su base hay un esquema compartido de **1.290 dimensiones categóricas** que cubren trasfondo, psicología, capacidad y comportamiento. Las personas combinan generación sintética consciente de dependencias con grounding humano basado en evidencia; un coreset determinista y filtrado por calidad de **un millón de personas** se publica para investigación en [Hugging Face](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release). La telemetría compartida, la verificación propia de cada tarea y los informes conectan respuestas y trayectorias individuales con hallazgos a nivel de subgrupo y población. El nombre alude a *The Matrix*: un mundo simulado útil para exploración, pruebas de estrés y generación de hipótesis — **no un sustituto de la evidencia de personas reales**. ## Novedades y reconocimiento - **Comentario 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/)) - **Selección de investigación** — Destacado en [Hugging Face Papers](https://huggingface.co/papers/2608.04205) ([Papers del día, 2026-08-10](https://huggingface.co/papers/date/2026-08-10)) - **Medios** — [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 (vía 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 Turquía](https://www.forbes.com.tr/saglik/hastaya-dokunmadan-once-8-3-milyar-kez-denemek-sagligin-yeni-test-dunyasi-matraix) · [WIRED Chequia](https://www.wired.cz/news-beat/harvard-a-mit-vytvorily-ai-simulaci-obsahujici-83-miliardy-virtualnich-lidi) - **Comentario de la industria** — Comentado por el vicepresidente y CTO de Cisco [Gianpaolo Barozzi](https://lnkd.in/p/gE9cV2nw) - **Redes** — Destacado como [historia en tendencia de X](https://x.com/i/trending/2086626337561911419) ## Lanzamientos - **[2026-08-04]** Informe técnico en arXiv: [MatrAIx: Simulating the World with 8.3 Billion Persona Agents](https://arxiv.org/abs/2608.04205) (`2608.04205`). - **[2026-08-01]** Publicado [Persona 1M](https://huggingface.co/datasets/MatrAIx2026/MatrAIx_Persona_1M_Public_Release) en Hugging Face (~1M personas filtradas por calidad). - **[2026-07-31]** Código abierto del Playground y la biblioteca de tareas: [MatrAIx-Persona-8B](https://github.com/MatrAIx-ai/MatrAIx-Persona-8B). - **[2026-07-29]** Nota de posición: [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/) y Python 3.12 - Node.js 20+ (solo frontends de Playground / viewer) - Claves de API de modelo para ejemplos de agentes de persona — ver [agents.md](../environment/agents.md) > **Usuarios de Windows**: ejecuten todo dentro de > [WSL2](https://learn.microsoft.com/windows/wsl/install) — abran PowerShell, > ejecuten `wsl --install` (instala Ubuntu), luego clonen este repositorio > **dentro del sistema de archivos de WSL** (p. ej. `~/MatrAIx`, no > `/mnt/c/…`, que es mucho más lento) y activen *WSL integration* en Docker > Desktop → Settings → Resources. Después, todos los comandos de este README > funcionan tal cual. No se admite PowerShell/cmd nativo (los verificadores de > tareas requieren `bash`). ## Instalación ```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 ``` Ejecuta jobs y tareas con **`uv run matraix run …`**: configura el entorno de lanzamiento completo y delega en el runtime Harbor. Las utilidades del runtime (p. ej. `harbor view`, `harbor upload`) siguen bajo **`uv run harbor …`**. Configura la clave de API del modelo correspondiente a tu proveedor antes de ejecutar tareas por GUI o CLI (la prueba de humo no la necesita): ```bash export ANTHROPIC_API_KEY="sk-ant-..." # modelos anthropic/claude-* # export OPENAI_API_KEY="sk-..." # modelos openai/gpt-* ``` Consulta la matriz completa de claves en [agents.md](../environment/agents.md). Playground también puede cargar claves desde `application/playground/.env.local`. ### Importar Persona 1M (recomendado) El `matraix-persona-dev-sample` del repo (~200) es solo para pruebas de humo. Para cohortes reales y muestreo en Playground, importa el 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`. Detalles: [Handbook § Persona 1M](../README.md#3-persona-1m-recommended). ## Inicio rápido ### Pruebas de humo (smoke tests) Tras instalar, ejecuta estas dos comprobaciones (sin clave de API). Juntas confirman la ruta por defecto de Survey, Chat, Web y OS-app: | Comprobación | Confirma que puedes ejecutar | Comando | |--------------|------------------------------|---------| | **Sin Docker** | Survey y Chat | `uv run matraix smoke application/tasks/example-survey_product-feedback` | | **Con Docker** | Web y OS-app | `uv run matraix run -c configs/jobs/example-job-recipe/harbor-smoke-local.yaml` | La primera suele terminar en segundos con `Smoke: ok`. La segunda construye una imagen local la primera vez (unos minutos) y escribe en `jobs/harbor-smoke-local/`. Pasos: [quickstart §3](../quickstart.md#3-smoke-tests-two-lanes). ### Ejecuciones de tareas por GUI Playground elige tareas, muestrea personas y lanza los mismos jobs de Matraix Playground que el modo auto de la CLI. Inicia API + frontend (dos terminales): ```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 ``` Abre **http://localhost:5173** → Playground → elige una cohorte de personas → elige tareas Survey / Chat / Web / OS app → **Lock pipeline** → **Run eval**. Detalles: [Playground §10](../quickstart.md#10-playground--play-tasks-visually). ### Desarrollo / ejecución por CLI **Desarrollar** — copia una tarea de referencia en `application/tasks/`, edita `task.toml` / `instruction.md` / `input/` / el verificador (verifier) y regístrala en Playground ([task-guide.md](../application/task-guide.md)): ```bash cp -R application/tasks/example-survey_product-feedback \ application/tasks/ ``` | Tipo | Tarea de referencia | |------|---------------------| | 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` | **Ejecutar** — genera un job de Matraix Playground (fija agent + model) y ejecútalo: ```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 # Usa las líneas de export + la ruta del recipe que imprime el script, p. ej.: uv run matraix run -c configs/jobs/application-task-job-recipe/example-survey-product-feedback-auto-n1.yaml ``` Lotes (`--sample-size N`), filtros y ejemplos chat / web / os-app: [docs/quickstart.md](../quickstart.md). ## Docs **[MatrAIx Handbook](../README.md)** — guías y docs de persona / application / environment.

Arquitectura MatrAIx

## Estructura del repositorio ```text MatrAIx/ ├── persona/ Schema, datasets, pipelines de síntesis/curación/validación │ ├── schema/ Schema de persona de 1.290 dimensiones │ ├── datasets/ Pool de muestras de desarrollo y YAMLs de persona │ ├── validation/ Suites de grounding / validación de calidad │ └── scripts/ Helpers de job y pipeline de persona ├── application/ │ ├── tasks/ Specs de tareas Survey · chat · web · os-app │ ├── task-spec/ Contratos compartidos de tarea │ ├── playground/ Runner visual (API backend + frontend) │ └── scripts/ generate_application_job.py y tooling de tareas ├── environment/ │ ├── runtime/ Runtime de Matraix Playground │ ├── agents/ Agentes condicionados a persona │ ├── task-environments/ Imágenes Docker / sidecars │ └── adapters/ Adaptadores externos (p. ej. SimpleQA) ├── packages/ playground · rewardkit · harbor-langsmith ├── apps/viewer/ Frontend emparejado con `harbor view` ├── configs/jobs/ Recipes de job de Matraix Playground (curados y generados) ├── docs/ Handbook — persona/ · application/ · environment/ ├── examples/ Tareas de ejemplo mínimas ├── src/matraix/ Entry points del paquete Python ├── scripts/ Helpers a nivel de repositorio ├── tests/ Tests unitarios / de entorno └── jobs/ Salidas locales de Matraix Playground (gitignored) ``` Los datasets grandes generados quedan fuera de git (ver el release de Hugging Face arriba). ## Únete a la comunidad [![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. Únete a Discord — nickname **`Full Name - Affiliation`**. Completa el Google Form (trasfondo, intereses, autoría / agradecimientos en papers). 2. ¡Saluda! Nos gusta conectar a quienes comparten intereses o experiencia. 3. Participa en la comunidad de investigación MatrAIx para colaborar o contribuir. ## Cita Si usas MatrAIx, el dataset Persona 1M o resultados de este repositorio, cita: ```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} } ``` Artículo: [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 ## Licencia MIT — ver [LICENSE](../../LICENSE).