# salesforce/ai-economist architecture

> Architecture diagram of the GitHub repository salesforce/ai-economist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/salesforce/ai-economist
- Repository: https://github.com/salesforce/ai-economist

## Overview

AI Economist is a modular socio-economic simulation framework with Gym-style reset/step behavior. Users configure a scenario and submit worker and planner actions; the environment advances component and scenario rules, computes rewards and returns observations, rewards, and completion data. The architecture also includes reusable economic mechanics, COVID-19 health-policy simulation and data, and a separate real-business-cycle training implementation. The graph reflects README documentation and sampled source; links among unsampled scenario features are omitted where their wiring cannot be verified.

Main entry points: [`ai_economist/foundation/base/base_env.py`](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/base/base_env.py) (Environment lifecycle), [`ai_economist/foundation/components`](https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/components) (Composable components), [`ai_economist/foundation/scenarios/covid19/covid19_env.py`](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/covid19/covid19_env.py) (COVID economy), [`ai_economist/foundation/env_wrapper.py`](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/env_wrapper.py) (Environment wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Simulation engine"]
  node_wrapper["Environment wrapper<br/>[env_wrapper.py]"]
  node_baseenv["Environment lifecycle<br/>[base_env.py]"]
  node_world["World state<br/>[world.py]"]
  node_agents["Workers and planner"]
end

subgraph group_mechanics["Economic mechanics"]
  node_components["Composable components"]
  node_build["Building and gathering<br/>[build.py]"]
  node_movement["Movement rules<br/>[move.py]"]
  node_labor["Labor market<br/>[simple_labor.py]"]
  node_auction["Double auction"]
  node_redistribution["Tax redistribution<br/>[redistribution.py]"]
  node_entities["Resources and entities"]
end

subgraph group_scenarios["Simulation scenarios"]
  node_woodscenario["Wood and stone<br/>[dynamic_layout.py]"]
  node_onescenario["One-step economy"]
  node_covid["COVID economy<br/>[covid19_env.py]"]
  node_covidcomponents["Health policy mechanics"]
end

subgraph group_learning["Learning and data"]
  node_coviddatasets["COVID datasets"]
  node_training["Foundation training<br/>[training_script.py]"]
  node_rbc["Business-cycle training<br/>[cuda_manager.py]"]
  node_rbcentry["Best-response runner"]
end

node_users(("Policy researchers"))
node_externaldata(("COVID data source"))

node_users -->|"configure and act"| node_wrapper
node_wrapper -->|"reset and step"| node_baseenv
node_baseenv -->|"updates state"| node_world
node_baseenv -->|"manages actors"| node_agents
node_baseenv -->|"steps components"| node_components
node_components -->|"apply rules"| node_world
node_components -->|"includes"| node_build
node_components -->|"includes"| node_movement
node_components -->|"includes"| node_labor
node_components -->|"includes"| node_auction
node_components -->|"includes"| node_redistribution
node_baseenv -->|"registers entities"| node_entities
node_baseenv -->|"scenario behavior"| node_woodscenario
node_baseenv -->|"scenario behavior"| node_onescenario
node_baseenv -->|"scenario behavior"| node_covid
node_covid -->|"uses health rules"| node_covidcomponents
node_covid -.->|"loads data"| node_coviddatasets
node_coviddatasets -.->|"fetches policy data"| node_externaldata
node_training -->|"trains through"| node_wrapper
node_rbcentry -->|"runs training"| node_rbc

click node_wrapper "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/env_wrapper.py"
click node_baseenv "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/base/base_env.py"
click node_world "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/base/world.py"
click node_agents "https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/agents"
click node_components "https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/components"
click node_build "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/build.py"
click node_movement "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/move.py"
click node_labor "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/simple_labor.py"
click node_auction "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/continuous_double_auction.py"
click node_redistribution "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/redistribution.py"
click node_entities "https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/entities"
click node_woodscenario "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/simple_wood_and_stone/dynamic_layout.py"
click node_onescenario "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/one_step_economy/one_step_economy.py"
click node_covid "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/covid19/covid19_env.py"
click node_covidcomponents "https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/covid19_components.py"
click node_coviddatasets "https://github.com/salesforce/ai-economist/tree/master/ai_economist/datasets/covid19_datasets"
click node_training "https://github.com/salesforce/ai-economist/blob/master/ai_economist/training/training_script.py"
click node_rbc "https://github.com/salesforce/ai-economist/blob/master/ai_economist/real_business_cycle/rbc/cuda_manager.py"
click node_rbcentry "https://github.com/salesforce/ai-economist/blob/master/ai_economist/real_business_cycle/train_bestresponse.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wrapper,node_baseenv,node_world,node_agents toneBlue
class node_components,node_build,node_movement,node_labor,node_auction,node_redistribution,node_entities toneAmber
class node_woodscenario,node_onescenario,node_covid,node_covidcomponents toneMint
class node_coviddatasets,node_training,node_rbc,node_rbcentry toneRose
class node_users,node_externaldata toneIndigo
```

## Components

### Simulation engine

- [Environment wrapper](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/env_wrapper.py): `ai_economist/foundation/env_wrapper.py`
- [Environment lifecycle](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/base/base_env.py): `ai_economist/foundation/base/base_env.py`
- [World state](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/base/world.py): `ai_economist/foundation/base/world.py`
- [Workers and planner](https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/agents): `ai_economist/foundation/agents`

### Economic mechanics

- [Composable components](https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/components): `ai_economist/foundation/components`
- [Building and gathering](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/build.py): `ai_economist/foundation/components/build.py`
- [Movement rules](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/move.py): `ai_economist/foundation/components/move.py`
- [Labor market](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/simple_labor.py): `ai_economist/foundation/components/simple_labor.py`
- [Double auction](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/continuous_double_auction.py): `ai_economist/foundation/components/continuous_double_auction.py`
- [Tax redistribution](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/redistribution.py): `ai_economist/foundation/components/redistribution.py`
- [Resources and entities](https://github.com/salesforce/ai-economist/tree/master/ai_economist/foundation/entities): `ai_economist/foundation/entities`

### Simulation scenarios

- [Wood and stone](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/simple_wood_and_stone/dynamic_layout.py): `ai_economist/foundation/scenarios/simple_wood_and_stone/dynamic_layout.py`
- [One-step economy](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/one_step_economy/one_step_economy.py): `ai_economist/foundation/scenarios/one_step_economy/one_step_economy.py`
- [COVID economy](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/scenarios/covid19/covid19_env.py): `ai_economist/foundation/scenarios/covid19/covid19_env.py`
- [Health policy mechanics](https://github.com/salesforce/ai-economist/blob/master/ai_economist/foundation/components/covid19_components.py): `ai_economist/foundation/components/covid19_components.py`

### Learning and data

- [COVID datasets](https://github.com/salesforce/ai-economist/tree/master/ai_economist/datasets/covid19_datasets): `ai_economist/datasets/covid19_datasets`
- [Foundation training](https://github.com/salesforce/ai-economist/blob/master/ai_economist/training/training_script.py): `ai_economist/training/training_script.py`
- [Business-cycle training](https://github.com/salesforce/ai-economist/blob/master/ai_economist/real_business_cycle/rbc/cuda_manager.py): `ai_economist/real_business_cycle/rbc/cuda_manager.py`
- [Best-response runner](https://github.com/salesforce/ai-economist/blob/master/ai_economist/real_business_cycle/train_bestresponse.py): `ai_economist/real_business_cycle/train_bestresponse.py`

### Other components

- **Policy researchers**
- **COVID data source**

## Connections

- Policy researchers → Environment wrapper: configure and act
- Environment wrapper → Environment lifecycle: reset and step
- Environment lifecycle → World state: updates state
- Environment lifecycle → Workers and planner: manages actors
- Environment lifecycle → Composable components: steps components
- Composable components → World state: apply rules
- Composable components → Building and gathering: includes
- Composable components → Movement rules: includes
- Composable components → Labor market: includes
- Composable components → Double auction: includes
- Composable components → Tax redistribution: includes
- Environment lifecycle → Resources and entities: registers entities
- Environment lifecycle → Wood and stone: scenario behavior
- Environment lifecycle → One-step economy: scenario behavior
- Environment lifecycle → COVID economy: scenario behavior
- COVID economy → Health policy mechanics: uses health rules
- COVID economy → COVID datasets: loads data
- COVID datasets → COVID data source: fetches policy data
- Foundation training → Environment wrapper: trains through
- Best-response runner → Business-cycle training: runs training