AI Economist / Foundation

A flexible, modular, and composable framework for modeling socio-economic behaviors and dynamics with multi-agent reinforcement learning.

Foundation is an open-source simulation framework from Salesforce Research that lets you build rich economic environments and train AI agents — including workers and governments — to discover optimal policies. It provides an OpenAI Gym-compatible API and integrates with popular RL frameworks including RLlib and WarpDrive.

Installation

Install Foundation via pip or from source in a few commands.

Quickstart

Run your first economic simulation and see agents in action.

Core Concepts

Understand Scenarios, Components, Agents, and Entities.

API Reference

Full reference for BaseEnvironment, Components, and Agents.

What is Foundation?

Foundation models a society of mobile agents (workers) and a social planner (government). The planner sets macroeconomic policies — such as tax rates — and worker agents respond by gathering resources, trading, and building. You can study how different policies affect economic outcomes like equality and productivity.

This framework was used to build the AI Economist, which learned tax policies that improve both equality and productivity compared to established economic theories.

Gather, Trade & Build

The flagship multi-agent economic simulation environment.

COVID-19 & Economy

Simulate the interplay between pandemic policy and economic outcomes.

Training with RLlib

Distributed multi-agent RL training with Ray RLlib.

GPU Training with WarpDrive

Massively parallel GPU-accelerated training using CUDA.

Key features

Gym-compatible API

Foundation exposes a standard reset() / step() interface compatible with OpenAI Gym, so it integrates easily with any RL framework.

Composable building blocks

Mix and match Components (e.g., Move, Build, Trade, Taxation) to construct new simulation dynamics without rewriting core logic.

Two-level hierarchical RL

The planner agent operates at a higher level, setting policy that worker agents respond to — enabling curriculum and two-level RL training strategies.

GPU-accelerated simulation

CUDA C implementations of key simulation steps allow thousands of parallel environment rollouts on a single GPU via the WarpDrive framework.

Real-world data integration

The COVID-19 simulation is fitted with real epidemiological and economic data, enabling data-driven policy analysis.

Getting started

1. Install Foundation

   pip install ai-economist
   
2. Import and create an environment

   import ai_economist.foundation as foundation
   
   env = foundation.make_env_instance(
       scenario_name="simple_wood_and_stone/dynamic_layout",
       n_agents=4,
       world_size=[25, 25],
       episode_length=1000,
   )
   
3. Run a simulation loop

   obs = env.reset()
   
   for t in range(env.episode_length):
       actions = {agent.idx: agent.action_space.sample()
                  for agent in env.all_agents}
       obs, rew, done, info = env.step(actions)
       if done:
           break
   
4. Explore tutorials

   Check out the Quickstart guide or open the Google Colab notebooks to run interactive examples in your browser.

Foundation requires Python 3.7 or later. GPU training features require a CUDA-capable GPU with the WarpDrive package installed.