AI Social Lab

AI Social Lab is a local-first simulation sandbox for multi-agent social scenes, world rules, and experiment orchestration.

The repository currently supports:

• a Vite + React web app
• an Electron shell for desktop use
• local inference through Ollama
• cloud inference through Gemini
• batch experiment runners and a local orchestration API

For the exhaustive developer manual, see README.developer.md.

Requirements

• Node.js 18+
• npm 9+
• Optional: Ollama for local generation
• Optional: Gemini API key for cloud generation

Install

npm install

Main Commands

npm start

Starts the Vite development server on http://127.0.0.1:3000.

npm run electron:dev

Starts the Vite dev server and the Electron shell together.

npm run build

Builds the web app into build/.

npm run electron:build

Builds the web app and packages a Windows desktop build with electron-packager.

Generated Assets

The repo keeps a small set of generated files in sync before dev/build runs:

• public/vector.worker.js is synced from src/services/vector.worker.js
• src/locales/*.json is synced from src/translations.js

If you need to run them directly:

npm run sync:generated

Validation And Tests

npm run world:validate
npm test

Targeted experiment/runtime tests can also be run with vitest directly.

Batch And API Workflows

Run the local experiment API:

npm run society:api

Run a batch pipeline:

npm run society:batch -- --ticks 60 --agents 20

Useful modes:

• --mode protocol
• --mode ablation
• --mode benchmark
• --mode benchmark-mc
• --mode benchmark-distributed

Ports

• Web dev server: 127.0.0.1:3000
• Ollama default: 127.0.0.1:11434
• Society API server: 127.0.0.1:4488

Notes

• The current user-facing product name is AI Social Lab.
• The npm package name remains aiagent-app.
• Desktop packaging uses electron-packager, not electron-builder.

Troubleshooting

See TROUBLESHOOTING.md.