Introduction

Foundation: a modular framework for economic simulation and multi-agent reinforcement learning

Foundation is an open-source Python framework for building flexible, modular, and composable environments that model socio-economic behaviors and dynamics in a society with both agents and governments. It is the simulation engine underlying the AI Economist research project from Salesforce Research.

Foundation exposes a Gym-compatible API—reset and step—so any multi-agent RL library can drive the simulation without modification.

The AI Economist research

Foundation was created to support research into AI-driven economic policy design. The framework has been used in three published papers:

• The AI Economist: Improving Equality and Productivity with AI-Driven Tax Policies — Zheng et al., 2020. Demonstrates how RL can learn tax policies that improve both equality and productivity in simulated economies.
• The AI Economist: Optimal Economic Policy Design via Two-level Deep Reinforcement Learning — Zheng et al., 2021. Introduces a two-level RL approach in which a government agent and worker agents are trained simultaneously.
• Building a Foundation for Data-Driven, Interpretable, and Robust Policy Design using the AI Economist — Trott et al., 2021. Applies Foundation to the COVID-19 pandemic, fitting simulated dynamics to real-world data.

Architecture overview

The simulation lives in ai_economist/foundation/ and is organized into five cooperating layers:

Layer	Description
Scenarios	Compose Components to define the full world dynamics, compute rewards, and expose states for visualization. A Scenario is the top-level environment object you interact with.
Components	Modular building blocks that add specific dynamics and action subspaces to a Scenario (e.g., Build, Gather, ContinuousDoubleAuction, PeriodicBracketTax).
Agents	Represent economic actors. Mobile agents act as workers; the planner agent acts as a social planner or government.
Entities	Endogenous variables (e.g., Labor), landmarks (e.g., Water, House), and collectible resources (e.g., Wood, Stone) that populate the world.
Base classes	BaseEnvironment and BaseComponent define the extension contracts that custom Scenarios and Components must implement.

All classes are accessed through registries:

from ai_economist import foundation

foundation.scenarios   # Scenario class registry
foundation.components  # Component class registry
foundation.agents      # Agent class registry
foundation.resources   # Resource class registry
foundation.landmarks   # Landmark class registry
foundation.endogenous  # Endogenous variable registry

Gym-style API

Every Scenario instance exposes the standard two-method loop:

obs                        = env.reset()
obs, rew, done, info  = env.step(actions)

obs, rew, and done are dictionaries keyed by agent index (and "p" for the planner). This makes Foundation easy to integrate with RLlib, WarpDrive, or any other multi-agent training framework.

Included scenarios

Four scenarios ship with the package:

Scenario name	Description
uniform/simple_wood_and_stone	2D grid world with Wood and Stone resources; agents gather, trade, and build houses. Layout generated procedurally.
layout_from_file/simple_wood_and_stone	Same dynamics as above, but the world layout is loaded from a .txt map file.
multi_zone/simple_wood_and_stone	Multi-zone variant of the Wood and Stone world.
quadrant/simple_wood_and_stone	Quadrant layout variant.
split_layout/simple_wood_and_stone	Split-layout variant.
one-step-economy	Minimal one-step economy for rapid prototyping.
CovidAndEconomySimulation	Epidemiological + economic simulation fitted to real COVID-19 data.

Installation

Install Foundation via pip or from source, and verify your setup.

Quickstart

Create your first environment, run a reset/step loop, and inspect observations.

GitHub

Browse the source code, file issues, and read the contribution guide.

Slack community

Join the AI Economist Slack to discuss research and get help.

License and ethics

Foundation is released under the BSD-3-Clause License. The authors have published Simulation Cards that cover the intended use and ethical review of the framework and its COVID-19 extension.