Agent Econ

Agent Econ is an agent-based macroeconomy simulation running in the browser. Micro-level household and firm behavior is simulated in deterministic tick phases, while the UI renders macro trends and agent-level flows in real time.

Current State

• Active runtime: TypeScript + Web Worker (packages/sim-core, apps/web)
• Hosting target: GitHub Pages (static)
• Python source is archived in legacy-python/ for reference

Implementation details are documented in IMPLIMENTATION_REPORT.md.

Quick Start

Prerequisites:

• Node.js 22+

Install:

npm install

Run locally:

npm run dev

Typecheck:

npm run typecheck

Production build:

npm run build

Project Structure

apps/
  web/                 # Vite web app (controls, charts, canvas rendering)
packages/
  sim-core/            # Simulation kernel, contracts, phase logic
.github/workflows/
  deploy-pages.yml     # GitHub Pages deploy workflow
data/
  scenarios/           # Scenario inputs (includes baseline.python.v1.json)
  baselines/           # Reserved for calibration artifacts
legacy-python/         # Archived Python source/config from pre-web migration

Simulation Architecture (Web)

The simulation runs as a worker-driven tick loop in the browser.

Tick phase order:

1. Production
2. Market
3. Payday
4. Profit Distribution
5. Labor
6. Strategy
7. Banking

The engine streams per-tick outputs to the UI:

• Summary metrics (sales, wages, unemployment, dividends, production)
• Event counts
• Transaction events (used for particle animations)

Visualization

Current visualization features:

• Full dark-mode UI
• Macro charts for sales, unemployment, wages, dividends
• Agent-space rendering (firms, households, banks)
• Ownership links (firm -> owner household)
• Spending and wage particle flows
• Metadata panel hidden by default and toggled from controls
• Device-pixel-ratio aware canvas rendering for crisp graphics

Configuration

Primary runtime config currently lives in:

• apps/web/src/runtime/defaultConfig.ts

Baseline scenario artifact copied from the Python project:

• data/scenarios/baseline.python.v1.json

Deployment (GitHub Pages)

Deployment workflow:

• .github/workflows/deploy-pages.yml

Vite repo-pages base path is configured in:

• apps/web/vite.config.ts

Pushes to main trigger build and Pages deploy.

Notes

• This repository is mid-migration; core web runtime is working, with additional hardening and calibration work remaining.
• Archived Python code in legacy-python/ is retained as historical reference, not active runtime.