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—Documentation Index
Fetch the complete documentation index at: https://mintlify.com/salesforce/ai-economist/llms.txt
Use this file to discover all available pages before exploring further.
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 inai_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. |
Gym-style API
Every Scenario instance exposes the standard two-method loop: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.