Registries

Registry system for managing Components, Scenarios, Agents, and Entities

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:

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

2. 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 {}
   
3. 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)