babylon.models.entities.institution

Institution entity models for the Babylon simulation (Feature 040).

Defines the Institution base entity and supporting models: - InternalBalanceOfForces: Factional weight distribution - ReproductionMechanism: Self-perpetuation capacity - SpawningBlueprint: Template for replacement Organizations - InstitutionOrgRelation: Institution-Organization housing relationship - Institution: Third-layer entity between substrate and agents - FactionShiftEvent: Hegemonic fraction change event - ReproductionEvent: Organization spawning event - BonapartistModeEvent: Bonapartist threshold crossing event

All models are frozen (immutable) Pydantic BaseModels.

See also

specs/040-institution-base-model/data-model.md: Entity definitions. babylon.models.enums: ApparatusType, SocialFunction, etc.

Classes

`BonapartistModeEvent`(**data)	Returned when BONAPARTIST weight crosses the Bonapartist threshold.
`FactionShiftEvent`(**data)	Returned when update_internal_balance changes the hegemonic fraction.
`Institution`(**data)	Third-layer entity representing crystallized social relations (Feature 040).
`InstitutionOrgRelation`(**data)	Relationship between institution and housed Organization (Feature 040).
`InternalBalanceOfForces`(**data)	Factional weight distribution within an institution (Feature 040).
`ReproductionEvent`(**data)	Returned when an institution spawns a replacement Organization.
`ReproductionMechanism`(**data)	Self-perpetuation capacity of an institution (Feature 040).
`SpawningBlueprint`(**data)	Template for replacement Organization creation (Feature 040).

class babylon.models.entities.institution.InternalBalanceOfForces(**data)[source]

Bases: BaseModel

Factional weight distribution within an institution (Feature 040).

Three ruling-class fractions compete for hegemony within each institution. Weights always sum to 1.0 (tolerance +/- 0.01). The hegemonic fraction (highest weight) modulates housed Organization OODA orientation.

Parameters:

liberal_technocratic (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
revanchist_fascist (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
institutionalist_bonapartist (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
internal_contestation (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

liberal_technocratic: Weight of consent-based rule faction [0, 1].

revanchist_fascist: Weight of naked repression faction [0, 1].

institutionalist_bonapartist: Weight of self-preservation faction [0, 1].

internal_contestation: How actively factional warfare is occurring [0, 1].

Reference: FR-005, FR-006.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

liberal_technocratic: float

revanchist_fascist: float

institutionalist_bonapartist: float

internal_contestation: float

property hegemonic_fraction: RulingClassFraction: Faction with highest weight.

class babylon.models.entities.institution.ReproductionMechanism(**data)[source]

Bases: BaseModel

Self-perpetuation capacity of an institution (Feature 040).

Tracks the formal mechanisms that allow an institution to reproduce itself: recruitment, training, succession, budget independence, and legal self-perpetuation. The computed reproduction_capacity score determines how effectively an institution replaces lost members.

Parameters:

recruitment_pipeline (bool)
training_program (bool)
succession_protocol (bool)
budget_independence (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
legal_self_perpetuation (bool)

recruitment_pipeline: Has formal member intake process.

training_program: Has formal training/socialization.

succession_protocol: Has leadership succession plan.

budget_independence: Fraction of budget from own sources [0, 1].

legal_self_perpetuation: Has legal mandate to exist.

Reference: FR-012.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

recruitment_pipeline: bool

training_program: bool

succession_protocol: bool

budget_independence: float

legal_self_perpetuation: bool

property reproduction_capacity: float

Composite reproduction capacity score.

Formula: (sum(bools) / 4) * 0.7 + budget_independence * 0.3

The four boolean mechanisms contribute 70% of capacity, budget independence contributes 30%.

class babylon.models.entities.institution.SpawningBlueprint(**data)[source]

Bases: BaseModel

Template for replacement Organization creation (Feature 040).

Stored by institutions to define how replacement Organizations are created when housed ones are destroyed. Spawned orgs inherit from the blueprint, modified by the institution’s current state.

Parameters:

org_type (OrgType)
default_class_character (ClassCharacter)
base_attributes (dict[str, Any])

org_type: Organization category to spawn.

default_class_character: Initial class character for spawned org.

base_attributes: Additional attributes for spawned org.

Reference: FR-016.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

org_type: OrgType

default_class_character: ClassCharacter

base_attributes: dict[str, Any]

class babylon.models.entities.institution.InstitutionOrgRelation(**data)[source]

Bases: BaseModel

Relationship between institution and housed Organization (Feature 040).

Tracks the material and political dimensions of how an institution houses and shapes an Organization.

Parameters:

institution_id (Annotated[str, MinLen(min_length=1)])
organization_id (Annotated[str, MinLen(min_length=1)])
resource_provision (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
legal_cover (bool)
legitimacy_transfer (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
action_oversight (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
factional_alignment (RulingClassFraction | None)

institution_id: Parent institution ID.

organization_id: Housed organization ID.

resource_provision: Fraction of institution resources provided [0, 1].

legal_cover: Whether institution provides legal protection.

legitimacy_transfer: How much institutional legitimacy transfers [0, 1].

action_oversight: How much institution constrains org actions [0, 1].

factional_alignment: Which faction the org aligns with, if any.

Reference: FR-011.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

institution_id: str

organization_id: str

resource_provision: float

legal_cover: bool

legitimacy_transfer: float

action_oversight: float

factional_alignment: RulingClassFraction | None

class babylon.models.entities.institution.Institution(**data)[source]

Bases: BaseModel

Third-layer entity representing crystallized social relations (Feature 040).

Institutions are the layer between substrate (SocialClass, Territory, Community) and agents (Organizations). They persist through member turnover, generate and constrain Organizations, maintain internal balance of forces, and serve as sites of class struggle.

Graph node type: _node_type="institution"

Parameters:

id (Annotated[str, MinLen(min_length=1)])
name (Annotated[str, MinLen(min_length=1)])
apparatus_type (ApparatusType)
social_function (SocialFunction)
class_inscription (ClassInscription)
internal_balance (InternalBalanceOfForces)
action_modifiers (dict[str, float])
budget (Annotated[float, Ge(ge=0)])
fixed_asset_territory_ids (list[str])
legal_authorities (frozenset[str])
personnel_capacity (Annotated[int, Ge(ge=0)])
formalization_level (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
institutional_inertia (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
legitimacy (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
housed_org_ids (list[str])
territory_ids (list[str])
jurisdiction (frozenset[str] | None)
lifecycle_function (LifecyclePhase | None)
reproduction (ReproductionMechanism)
spawning_blueprints (list[SpawningBlueprint])

id: Unique institution identifier.

name: Human-readable name.

apparatus_type: Althusserian classification.

social_function: Population need served.

class_inscription: Which class the institution serves.

internal_balance: Factional weight distribution.

action_modifiers: Override structural selectivity modifiers.

budget: Available resources.

fixed_asset_territory_ids: Territories with fixed infrastructure.

legal_authorities: Legal powers held.

personnel_capacity: Maximum personnel count.

formalization_level: Degree of bureaucratic formalization [0, 1].

institutional_inertia: Resistance to rapid change [0, 1].

legitimacy: Public perceived legitimacy [0, 1].

housed_org_ids: Organizations housed within.

territory_ids: Territories where institution operates.

jurisdiction: Jurisdiction scope (RSA types only).

lifecycle_function: D-P-D’ phase assignment.

reproduction: Self-perpetuation mechanisms.

spawning_blueprints: Templates for replacement orgs.

Reference: FR-001 through FR-016.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

name: str

apparatus_type: ApparatusType

social_function: SocialFunction

class_inscription: ClassInscription

internal_balance: InternalBalanceOfForces

action_modifiers: dict[str, float]

budget: float

fixed_asset_territory_ids: list[str]

legal_authorities: frozenset[str]

personnel_capacity: int

formalization_level: float

institutional_inertia: float

legitimacy: float

housed_org_ids: list[str]

territory_ids: list[str]

jurisdiction: frozenset[str] | None

lifecycle_function: LifecyclePhase | None

reproduction: ReproductionMechanism

spawning_blueprints: list[SpawningBlueprint]

class babylon.models.entities.institution.FactionShiftEvent(**data)[source]

Bases: BaseModel

Returned when update_internal_balance changes the hegemonic fraction.

Reference: FR-019, EventType.INSTITUTION_FACTION_SHIFT.

Parameters:

institution_id (Annotated[str, MinLen(min_length=1)])
old_fraction (RulingClassFraction)
new_fraction (RulingClassFraction)
weights (dict[str, float])

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

institution_id: str

old_fraction: RulingClassFraction

new_fraction: RulingClassFraction

weights: dict[str, float]

class babylon.models.entities.institution.ReproductionEvent(**data)[source]

Bases: BaseModel

Returned when an institution spawns a replacement Organization.

Reference: FR-019, EventType.INSTITUTION_REPRODUCTION.

Parameters:

institution_id (Annotated[str, MinLen(min_length=1)])
spawned_org_type (OrgType)
blueprint (SpawningBlueprint)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

institution_id: str

spawned_org_type: OrgType

blueprint: SpawningBlueprint

class babylon.models.entities.institution.BonapartistModeEvent(**data)[source]

Bases: BaseModel

Returned when BONAPARTIST weight crosses the Bonapartist threshold.

Reference: FR-019, EventType.INSTITUTION_BONAPARTIST_MODE.

Parameters:

institution_id (Annotated[str, MinLen(min_length=1)])
bonapartist_weight (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

institution_id: str

bonapartist_weight: float