Registries

Foundation uses a lightweight registry system to organize the building-block classes (Components, Scenarios, Agents, Resources, Landmarks, and Endogenous entities) that make up an environment. Registries provide a uniform API for looking up classes by name and ensure every registered entry inherits from the correct base class.

How registries work

Each registry is an instance of Registry(base_class). When you decorate a class with @registry.add, the class is stored internally and keyed by its name attribute (case-insensitive). You can then retrieve it with registry.get("ClassName").

from ai_economist.foundation.base.registrar import Registry

class BaseWidget:
    name = ""

widget_registry = Registry(BaseWidget)

@widget_registry.add
class RedWidget(BaseWidget):
    name = "RedWidget"

widget_registry.has("RedWidget")       # True
widget_registry.get("RedWidget")       # <class 'RedWidget'>
widget_registry.entries                # ['RedWidget']

`Registry` API

Constructor

Registry(base_class=None)

base_class

class

The base class that all entries must subclass. Pass None to skip the subclass check.

`add`

registry.add(cls) -> cls

Registers cls in the registry. Returns cls so it can be used as a decorator.

cls

class

required

The class to register. Must be a subclass of base_class (if set). The class’s name attribute must not contain a dot ("."). Lookup is case-insensitive.

@component_registry.add
class MyComponent(BaseComponent):
    name = "MyComponent"
    ...

`get`

registry.get(cls_name: str) -> class

Returns the registered class whose name matches cls_name (case-insensitive).

cls_name

str

required

Name of the class to retrieve.

Raises KeyError if no class with that name is registered.

MoveComponent = foundation.components.get("Gather")
instance = MoveComponent(world, episode_length)

`has`

registry.has(cls_name: str) -> bool

Returns True if a class named cls_name (case-insensitive) is in the registry.

cls_name

str

required

Name to check.

foundation.components.has("Gather")   # True
foundation.components.has("Unknown")  # False

`entries`

registry.entries  # list[str]

Returns a sorted list of all registered class names.

print(foundation.agents.entries)
# ['BasicMobileAgent', 'BasicPlanner']

The six registries

The top-level foundation package exposes six registries as module attributes:

import ai_economist.foundation as foundation

foundation.scenarios    # scenario_registry
foundation.components   # component_registry
foundation.agents       # agent_registry
foundation.resources    # resource_registry
foundation.landmarks    # landmark_registry
foundation.endogenous   # endogenous_registry

`foundation.scenarios`

Registry of BaseEnvironment scenario subclasses. Used to instantiate environments by name via foundation.make_env_instance. Built-in entries:

Name	Description
`CovidAndEconomySimulation`	Joint COVID-19 health and economic simulation.
`one-step-economy`	Minimal single-timestep economy scenario.
`uniform/simple_wood_and_stone`	2D gather-and-build economy with uniform resource layout.
`multi_zone/simple_wood_and_stone`	2D gather-and-build economy with multi-zone resource layout.
`quadrant/simple_wood_and_stone`	2D gather-and-build economy with quadrant resource layout.
`layout_from_file/simple_wood_and_stone`	Wood-and-stone scenario loaded from a layout file.
`split_layout/simple_wood_and_stone`	Wood-and-stone scenario with a split layout loaded from file.

env = foundation.make_env_instance(
    "uniform/simple_wood_and_stone",
    n_agents=4,
    world_size=[25, 25],
    episode_length=1000,
)

`foundation.components`

Registry of BaseComponent subclasses. The environment looks up and instantiates components from this registry during construction. Built-in entries:

Name	Description
`Build`	Allows mobile agents to build houses using collected resources.
`ContinuousDoubleAuction`	Continuous double-auction market for trading resources among agents.
`ControlUSStateOpenCloseStatus`	COVID-19 component for controlling state open/close policy.
`FederalGovernmentSubsidy`	COVID-19 component for distributing federal subsidies.
`Gather`	Allows mobile agents to move around the world and collect resources.
`PeriodicBracketTax`	Planner-controlled periodic bracket tax with redistribution.
`SimpleLabor`	Simple labor-commodity exchange component.
`VaccinationCampaign`	COVID-19 component for running vaccination campaigns.
`WealthRedistribution`	Equal redistribution of total coin among all mobile agents.

GatherClass = foundation.components.get("Gather")

`foundation.agents`

Registry of BaseAgent subclasses. Built-in entries:

Name	Description
`BasicMobileAgent`	Mobile agent that moves in the 2D world. Indexed by integer.
`BasicPlanner`	Social planner agent. No location. Always indexed as `"p"`.

AgentClass = foundation.agents.get("BasicMobileAgent")
agent = AgentClass(idx=0, multi_action_mode=False)

`foundation.resources`

Registry of Resource entity subclasses. Resources can be held in agent inventories and (if collectible=True) exist in the world map. Built-in entries:

Name	Collectible	Description
`Coin`	No	Currency used across all environments.
`Stone`	Yes	Collectible stone resource that agents can gather.
`Wood`	Yes	Collectible wood resource that agents can gather.

CoinClass = foundation.resources.get("Coin")

`foundation.landmarks`

Registry of Landmark entity subclasses. Landmarks exist exclusively in the world grid and are never held in agent inventories. Built-in entries:

Name	Ownable	Solid	Description
`House`	Yes	Yes	Buildable structure. Only its owner can occupy the cell.
`StoneSourceBlock`	No	No	Source tile where Stone is generated.
`Water`	No	Yes	Impassable water tile.
`WoodSourceBlock`	No	No	Source tile where Wood is generated.

StoneSourceBlock and WoodSourceBlock are auto-generated at import time from each collectible resource in resource_registry.

HouseClass = foundation.landmarks.get("House")

`foundation.endogenous`

Registry of Endogenous entity subclasses. Endogenous entities represent internal agent state quantities (e.g. effort) that are not physically exchangeable. Built-in entries:

Name	Description
`Labor`	Accumulated labor effort. Included in all environments by default.

foundation.endogenous.has("Labor")  # True

Registering a custom class

To register a custom component, agent, resource, landmark, or endogenous entity:

Subclass the base class

Create a class that inherits from the appropriate base (BaseComponent, BaseAgent, Resource, Landmark, or Endogenous) and set its name attribute to a unique string with no dots.

Apply the registry decorator

Decorate the class with @registry.add.

from ai_economist.foundation.base.base_component import (
    BaseComponent, component_registry
)

@component_registry.add
class MyTrade(BaseComponent):
    name = "MyTrade"
    component_type = "Trading"
    agent_subclasses = ["BasicMobileAgent"]
    required_entities = ["Coin"]

    def get_n_actions(self, agent_cls_name):
        if agent_cls_name == "BasicMobileAgent":
            return 5
        return None

    def get_additional_state_fields(self, agent_cls_name):
        return {}

    def component_step(self):
        pass

    def generate_observations(self):
        return {}

Ensure the file is imported

For the class to appear in the registry at runtime, the file that defines it must be imported before the registry is queried. For built-in classes, this is handled by the package’s __init__.py.

# In your project's __init__.py or entry point:
import my_project.components.my_trade  # triggers @component_registry.add

Lookup example

import ai_economist.foundation as foundation

# Check and retrieve a scenario
if foundation.scenarios.has("uniform/simple_wood_and_stone"):
    ScenarioClass = foundation.scenarios.get("uniform/simple_wood_and_stone")

# List all registered components
print(foundation.components.entries)
# ['Build', 'ContinuousDoubleAuction', 'ControlUSStateOpenCloseStatus',
#  'FederalGovernmentSubsidy', 'Gather', 'PeriodicBracketTax',
#  'SimpleLabor', 'VaccinationCampaign', 'WealthRedistribution']

# Instantiate an agent class
BasicMobile = foundation.agents.get("BasicMobileAgent")
agent = BasicMobile(idx=2, multi_action_mode=True)

Environment

Building Blocks

Built-in Components

How registries work

`Registry` API

Constructor

`add`

`get`

`has`

`entries`

The six registries

`foundation.scenarios`

`foundation.components`

`foundation.agents`

`foundation.resources`

`foundation.landmarks`

`foundation.endogenous`

Registering a custom class

Lookup example

Build docs developers (and LLMs) love

Environment

Building Blocks

Built-in Components

Documentation Index

​How registries work

​Registry API

​Constructor

​add

​get

​has

​entries

​The six registries

​foundation.scenarios

​foundation.components

​foundation.agents

​foundation.resources

​foundation.landmarks

​foundation.endogenous

​Registering a custom class

​Lookup example

Build docs developers (and LLMs) love

How registries work

`Registry` API

Constructor

`add`

`get`

`has`

`entries`

The six registries

`foundation.scenarios`

`foundation.components`

`foundation.agents`

`foundation.resources`

`foundation.landmarks`

`foundation.endogenous`

Registering a custom class

Lookup example