babylon.models.entity_registry

Entity ID registry - single source of truth for entity ID mappings.

This module provides canonical mappings between SocialRole enums and entity IDs, eliminating hardcoded magic strings like “C001”, “C002”, etc. throughout the codebase.

Usage:

from babylon.models.entity_registry import (: PERIPHERY_WORKER_ID, COMPRADOR_ID, role_to_entity_id, get_slot_name,

)

See also

babylon.models.enums.SocialRole for the enum definitions /ai-docs/decisions.yaml for ADR context

Module Attributes

`PERIPHERY_WORKER_ID`	Periphery Worker (P_w) - exploited proletariat in the global South.
`COMPRADOR_ID`	Comprador (P_c) - local bourgeoisie collaborating with imperialism.
`CORE_BOURGEOISIE_ID`	Core Bourgeoisie (C_b) - metropolitan capitalist class.
`LABOR_ARISTOCRACY_ID`	Labor Aristocracy (C_w) - privileged workers in the imperial core.
`CARCERAL_ENFORCER_ID`	Carceral Enforcer - guards, cops, prison staff (repressive apparatus).
`INTERNAL_PROLETARIAT_ID`	Internal Proletariat - core workers outside LA (precariat, unemployed, incarcerated).
`ROLE_TO_ENTITY_ID`	Maps SocialRole enum values to canonical entity IDs.
`ENTITY_ID_TO_ROLE`	entity IDs to SocialRole enum values.
`ENTITY_SLOT_NAMES`	Maps entity IDs to short slot names used in CSV columns and metrics.
`METRICS_ENTITY_IDS`	Entity IDs tracked in metrics observer (active during normal simulation).
`TERMINAL_CRISIS_ENTITY_IDS`	Entity IDs for terminal crisis dynamics (dormant until class decomposition).
`ALL_ENTITY_IDS`	All entity IDs including terminal crisis entities.

Functions

`entity_id_to_role`(entity_id)	Convert an entity ID to its SocialRole enum.
`get_slot_name`(entity_id)	Get the short slot name for an entity ID.
`role_to_entity_id`(role)	Convert a SocialRole enum to its canonical entity ID.

babylon.models.entity_registry.PERIPHERY_WORKER_ID: Final[str] = 'C001': Periphery Worker (P_w) - exploited proletariat in the global South.

babylon.models.entity_registry.COMPRADOR_ID: Final[str] = 'C002': Comprador (P_c) - local bourgeoisie collaborating with imperialism.

babylon.models.entity_registry.CORE_BOURGEOISIE_ID: Final[str] = 'C003': Core Bourgeoisie (C_b) - metropolitan capitalist class.

babylon.models.entity_registry.LABOR_ARISTOCRACY_ID: Final[str] = 'C004': Labor Aristocracy (C_w) - privileged workers in the imperial core.

babylon.models.entity_registry.CARCERAL_ENFORCER_ID: Final[str] = 'C005': Carceral Enforcer - guards, cops, prison staff (repressive apparatus).

babylon.models.entity_registry.INTERNAL_PROLETARIAT_ID: Final[str] = 'C006': Internal Proletariat - core workers outside LA (precariat, unemployed, incarcerated).

babylon.models.entity_registry.ROLE_TO_ENTITY_ID: Final[dict[SocialRole, str]] = {SocialRole.CARCERAL_ENFORCER: 'C005', SocialRole.COMPRADOR_BOURGEOISIE: 'C002', SocialRole.CORE_BOURGEOISIE: 'C003', SocialRole.INTERNAL_PROLETARIAT: 'C006', SocialRole.LABOR_ARISTOCRACY: 'C004', SocialRole.PERIPHERY_PROLETARIAT: 'C001'}: Maps SocialRole enum values to canonical entity IDs.

babylon.models.entity_registry.ENTITY_ID_TO_ROLE: Final[dict[str, SocialRole]] = {'C001': SocialRole.PERIPHERY_PROLETARIAT, 'C002': SocialRole.COMPRADOR_BOURGEOISIE, 'C003': SocialRole.CORE_BOURGEOISIE, 'C004': SocialRole.LABOR_ARISTOCRACY, 'C005': SocialRole.CARCERAL_ENFORCER, 'C006': SocialRole.INTERNAL_PROLETARIAT}

entity IDs to SocialRole enum values.

Type:: Inverse mapping

babylon.models.entity_registry.ENTITY_SLOT_NAMES: Final[dict[str, str]] = {'C001': 'p_w', 'C002': 'p_c', 'C003': 'c_b', 'C004': 'c_w', 'C005': 'c_e', 'C006': 'i_p'}: Maps entity IDs to short slot names used in CSV columns and metrics.

babylon.models.entity_registry.METRICS_ENTITY_IDS: Final[list[str]] = ['C001', 'C002', 'C003', 'C004']

Entity IDs tracked in metrics observer (active during normal simulation).

These are the four canonical entities in the imperial circuit scenario. Terminal crisis entities (C005, C006) are excluded as they only become active during class decomposition events.

babylon.models.entity_registry.TERMINAL_CRISIS_ENTITY_IDS: Final[list[str]] = ['C005', 'C006']: Entity IDs for terminal crisis dynamics (dormant until class decomposition).

babylon.models.entity_registry.ALL_ENTITY_IDS: Final[list[str]] = ['C001', 'C002', 'C003', 'C004', 'C005', 'C006']: All entity IDs including terminal crisis entities.

babylon.models.entity_registry.role_to_entity_id(role)[source]

Convert a SocialRole enum to its canonical entity ID.

Parameters:: role (SocialRole) – SocialRole enum value
Return type:: str
Returns:: Entity ID string (e.g., “C001”)
Raises:: KeyError – If the role has no entity ID mapping (e.g., LUMPENPROLETARIAT)

Example

>>> role_to_entity_id(SocialRole.PERIPHERY_PROLETARIAT)
'C001'

babylon.models.entity_registry.entity_id_to_role(entity_id)[source]

Convert an entity ID to its SocialRole enum.

Parameters:: entity_id (str) – Entity ID string (e.g., “C001”)
Return type:: SocialRole
Returns:: SocialRole enum value
Raises:: KeyError – If the entity ID is not recognized

Example

>>> entity_id_to_role("C001")
<SocialRole.PERIPHERY_PROLETARIAT: 'periphery_proletariat'>

babylon.models.entity_registry.get_slot_name(entity_id)[source]

Get the short slot name for an entity ID.

Slot names are used for CSV column prefixes and metrics keys.

Parameters:: entity_id (str) – Entity ID string (e.g., “C001”)
Return type:: str
Returns:: Short slot name (e.g., “p_w”)
Raises:: KeyError – If the entity ID is not recognized

Example

>>> get_slot_name("C001")
'p_w'