> ## 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.

# 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](https://www.einstein.ai/the-ai-economist) research project from Salesforce Research.

Foundation exposes a [Gym](https://github.com/openai/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](https://arxiv.org/abs/2004.13332)** — 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](https://arxiv.org/abs/2108.02755)** — 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](https://arxiv.org/abs/2108.02904)** — 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:

```python theme={null}
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:

```python theme={null}
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](https://mintlify.com/salesforce/ai-economist/installation.md)**
>
> Install Foundation via pip or from source, and verify your setup.

> **[Quickstart](https://mintlify.com/salesforce/ai-economist/quickstart.md)**
>
> Create your first environment, run a reset/step loop, and inspect observations.

> **[GitHub](https://github.com/salesforce/ai-economist)**
>
> Browse the source code, file issues, and read the contribution guide.

> **[Slack community](https://aieconomist.slack.com)**
>
> Join the AI Economist Slack to discuss research and get help.

## License and ethics

Foundation is released under the [BSD-3-Clause License](https://github.com/salesforce/ai-economist/blob/master/LICENSE.txt). The authors have published [Simulation Cards](https://github.com/salesforce/ai-economist/blob/master/Simulation_Card_Foundation_Economic_Simulation_Framework.pdf) that cover the intended use and ethical review of the framework and its COVID-19 extension.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.