---

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. 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? — Mayank Kejriwal (AI Scientist)
• Selección de investigación — Destacado en Hugging Face Papers (Papers del día, 2026-08-10)
• Medios — Forbes · NZZ am Sonntag · AI Era (vía 36Kr) · Numerama · Infobae · HispanicAd · AI Times · Startup Fortune · Forbes Turquía · WIRED Chequia
• Comentario de la industria — Comentado por el vicepresidente y CTO de Cisco Gianpaolo Barozzi
• Redes — Destacado como historia en tendencia de X

Lanzamientos

• [2026-08-04] Informe técnico en arXiv: MatrAIx: Simulating the World with 8.3 Billion Persona Agents (2608.04205).
• [2026-08-01] Publicado Persona 1M en Hugging Face (~1M personas filtradas por calidad).
• [2026-07-31] Código abierto del Playground y la biblioteca de tareas: MatrAIx-Persona-8B.
• [2026-07-29] Nota de posición: From Personas to Simulated Users.

Requisitos

• Docker
• 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

Usuarios de Windows: ejecuten todo dentro de WSL2 — 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

git clone <repo-url> && 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):

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. 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:

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.

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.

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):

# 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.

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):

cp -R application/tasks/example-survey_product-feedback \
  application/tasks/<your-task-name>

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:

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.

Docs

MatrAIx Handbook — guías y docs de persona / application / environment.

Estructura del repositorio

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

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:

@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 · Autores completos: GitHub Cite this repository (CITATION.cff) · Dataset: Persona 1M on Hugging Face.

Star History

Licencia

MIT — ver LICENSE.