Institution Reference

Technical reference for the Institution Base Model (Feature 040). Covers entity models, supporting models, event types, pure functions, graph queries, enums, graph integration, and configuration.

Import:

from babylon.models.entities.institution import (
    Institution,
    InternalBalanceOfForces,
    ReproductionMechanism,
    SpawningBlueprint,
    InstitutionOrgRelation,
    FactionShiftEvent,
    ReproductionEvent,
    BonapartistModeEvent,
)

from babylon.institution import (
    structural_selectivity,
    update_internal_balance,
    hegemonic_fraction_effect,
    community_embeddedness,
)

Entity Models

Institution

Third-layer entity between substrate (SocialClass, Territory, Community) and agents (Organizations). Frozen (immutable). Graph node type: _node_type="institution".

Field	Type	Default	Description
id	str		Unique institution identifier (min length 1).
name	str		Human-readable name (min length 1).
apparatus_type	ApparatusType		Althusserian classification (RSA, ISA, or Economic).
social_function	SocialFunction		Population need served by this institution.
class_inscription	ClassInscription	BOURGEOIS	Which class the institution serves.
internal_balance	InternalBalanceOfForces		Factional weight distribution.
action_modifiers	dict[str, float]	{}	Override structural selectivity modifiers (ActionType -> multiplier).
budget	float	0.0	Available resources (>= 0).
fixed_asset_territory_ids	list[str]	[]	Territories with fixed infrastructure.
legal_authorities	frozenset[str]	frozenset()	Legal powers held (e.g. “arrest”, “tax”, “legislate”).
personnel_capacity	int	0	Maximum personnel count (>= 0).
formalization_level	float	0.5	Degree of bureaucratic formalization [0, 1].
institutional_inertia	float	0.5	Resistance to rapid change [0, 1].
legitimacy	float	0.5	Public perceived legitimacy [0, 1].
housed_org_ids	list[str]	[]	Organization IDs housed within this institution.
territory_ids	list[str]	[]	Territories where institution operates.
jurisdiction	frozenset[str] | None	None	Jurisdiction scope. Only valid for RSA_ apparatus types.
lifecycle_function	LifecyclePhase | None	None	D-P-D’ lifecycle phase assignment.
reproduction	ReproductionMechanism		Self-perpetuation mechanisms.
spawning_blueprints	list[SpawningBlueprint]	[]	Templates for replacement Organizations.

Validators:

• jurisdiction must be None for non-RSA apparatus types.

• All action_modifiers values must be > 0.0.

• internal_balance faction weights must sum to 1.0 (tolerance +/- 0.01).

Supporting Models

InternalBalanceOfForces

Factional weight distribution within an institution. Three ruling-class fractions compete for hegemony. Weights always sum to 1.0.

Field	Type	Default	Description
liberal_technocratic	float		Weight of Liberal-Technocratic faction [0, 1].
revanchist_fascist	float		Weight of Revanchist-Fascist faction [0, 1].
institutionalist_bonapartist	float		Weight of Institutionalist-Bonapartist faction [0, 1].
internal_contestation	float	0.0	How actively factional warfare is occurring [0, 1].

Computed fields:

• hegemonic_fraction (RulingClassFraction): Faction with highest weight.

Validators:

• Faction weights must sum to 1.0 (tolerance: 0.99 <= total <= 1.01).

ReproductionMechanism

Self-perpetuation capacity of an institution. Tracks formal mechanisms for institutional reproduction.

Field	Type	Default	Description
recruitment_pipeline	bool	False	Has formal member intake process.
training_program	bool	False	Has formal training/socialization.
succession_protocol	bool	False	Has leadership succession plan.
budget_independence	float	0.0	Fraction of budget from own sources [0, 1].
legal_self_perpetuation	bool	False	Has legal mandate to exist.

Computed fields:

• reproduction_capacity (float): Composite score. Formula: (sum(bools) / 4) * 0.7 + budget_independence * 0.3. The four boolean mechanisms contribute 70%, budget independence 30%.

SpawningBlueprint

Template for replacement Organization creation. Stored on institutions to define how replacements are created when housed Organizations are destroyed.

Field	Type	Default	Description
org_type	OrgType		Organization category to spawn.
default_class_character	ClassCharacter		Initial class character for spawned org.
base_attributes	dict[str, Any]	{}	Additional attributes for spawned org.

InstitutionOrgRelation

Relationship between institution and housed Organization. Tracks material and political dimensions of housing.

Field	Type	Default	Description
institution_id	str		Parent institution ID (min length 1).
organization_id	str		Housed organization ID (min length 1).
resource_provision	float	0.0	Fraction of institution resources provided [0, 1].
legal_cover	bool	False	Whether institution provides legal protection.
legitimacy_transfer	float	0.0	How much institutional legitimacy transfers [0, 1].
action_oversight	float	0.0	How much institution constrains org actions [0, 1].
factional_alignment	RulingClassFraction | None	None	Which ruling-class faction the org aligns with.

Event Types

Three event types are returned by institution functions. These are data objects, not emitted directly – callers decide when and how to emit them via the EventBus.

FactionShiftEvent

Returned by update_internal_balance() when the hegemonic fraction changes. Maps to EventType.INSTITUTION_FACTION_SHIFT.

Field	Type	Description
institution_id	str	Institution whose hegemonic fraction changed.
old_fraction	RulingClassFraction	Previous hegemonic fraction.
new_fraction	RulingClassFraction	New hegemonic fraction.
weights	dict[str, float]	Updated faction weights.

ReproductionEvent

Returned when an institution spawns a replacement Organization. Maps to EventType.INSTITUTION_REPRODUCTION.

Field	Type	Description
institution_id	str	Institution that spawned the org.
spawned_org_type	OrgType	Type of organization spawned.
blueprint	SpawningBlueprint	Blueprint used for spawning.

BonapartistModeEvent

Returned by update_internal_balance() when the BONAPARTIST weight crosses the threshold while other fractions are below the exclusion threshold. Maps to EventType.INSTITUTION_BONAPARTIST_MODE.

Field	Type	Description
institution_id	str	Institution entering Bonapartist mode.
bonapartist_weight	float	Current BONAPARTIST faction weight [0, 1].

Pure Functions

All four functions are stateless. They take data in and return data out. No EventBus dependency.

Import:

from babylon.institution import (
    structural_selectivity,
    update_internal_balance,
    hegemonic_fraction_effect,
    community_embeddedness,
)

structural_selectivity

def structural_selectivity(
    institution: Institution,
    action_type: ActionType,
    defaults: dict[str, dict[str, float]],
) -> float: ...

Computes the cost modifier for an action within an institution. Lookup order:

1. institution.action_modifiers[action_type.value] – institution-level override.

2. defaults[apparatus_type.value][action_type.value] – apparatus-type defaults.

3. 1.0 – no modifier (fallback).

Returns a multiplier: < 1.0 means cheaper, > 1.0 means more expensive.

The defaults argument is typically InstitutionDefines.default_action_modifiers.

update_internal_balance

def update_internal_balance(
    balance: InternalBalanceOfForces,
    crisis_intensity: float,
    legitimacy: float,
    external_threat: float,
    alpha: float = 0.05,
    bonapartist_threshold: float = 0.4,
    bonapartist_exclusion_threshold: float = 0.35,
    institution_id: str = "unknown",
) -> tuple[InternalBalanceOfForces, list[FactionShiftEvent | BonapartistModeEvent]]: ...

Alpha-smoothed factional balance shift:

• Rising crisis_intensity drives REVANCHIST weight up (repression impulse).

• Falling legitimacy weakens LIBERAL weight (consent breaks down).

• Rising external_threat drives BONAPARTIST weight up (self-preservation).

Deltas:

revanchist_delta  = alpha * crisis_intensity
liberal_delta     = -alpha * (1.0 - legitimacy)
bonapartist_delta = alpha * external_threat

After applying deltas, weights are clamped to [0, 1] and renormalized to sum to 1.0. Contestation is computed as min(1.0, 1.0 - max_weight + 0.1).

Returns a tuple of (new balance, events). Events may include:

• FactionShiftEvent if the hegemonic fraction changed.

• BonapartistModeEvent if BONAPARTIST weight exceeds bonapartist_threshold and both other fractions are below bonapartist_exclusion_threshold.

hegemonic_fraction_effect

def hegemonic_fraction_effect(
    fraction: RulingClassFraction,
) -> dict[str, Any]: ...

Returns OODA modifier hints based on the hegemonic fraction:

Fraction	Preferred Actions	Escalation Reluctance	Strategy
LIBERAL_TECHNOCRATIC	[ASSIMILATE]	0.7	Consent-based rule
REVANCHIST_FASCIST	[REPRESS]	0.2	Naked repression
INSTITUTIONALIST_BONAPARTIST	[SURVEIL]	0.5	Self-preservation

Raises ValueError if fraction is not a valid RulingClassFraction.

community_embeddedness

def community_embeddedness(
    institution: Institution,
    graph: GraphProtocol,
) -> dict[str, float]: ...

Computes institution’s embeddedness in community hyperedges. For each territory the institution occupies, finds community nodes with matching territory_id and computes overlap ratio per CommunityType.

Returns dict mapping CommunityType string to embeddedness score [0, 1]. Returns empty dict if institution has no territory presence.

Enums

Enum	Values
ApparatusType	RSA: RSA_EXECUTIVE, RSA_MILITARY, RSA_POLICE, RSA_JUDICIAL, RSA_CARCERAL. ISA: ISA_EDUCATIONAL, ISA_RELIGIOUS, ISA_FAMILY, ISA_LEGAL, ISA_POLITICAL, ISA_COMMUNICATIONS, ISA_CULTURAL. Economic: ECONOMIC_PRODUCTIVE, ECONOMIC_FINANCIAL, ECONOMIC_EXTRACTIVE.
SocialFunction	EMPLOYMENT, EDUCATION, WORSHIP, POLICING, HEALTHCARE, CARE, ADJUDICATION, COMMUNICATION, LEGISLATION, INCARCERATION, MILITARY_DEFENSE, FINANCIAL_INTERMEDIATION
ClassInscription	BOURGEOIS, PROLETARIAN, CONTESTED
RulingClassFraction	LIBERAL_TECHNOCRATIC, REVANCHIST_FASCIST, INSTITUTIONALIST_BONAPARTIST
LifecyclePhase	D_DEPENDENT, P_PRODUCTIVE, D_PRIME_DEPENDENT

Edge types (added to EdgeType):

Type	Direction	Description
HOUSES	Institution -> Organization	Institution houses and shapes an Organization.

Event types (added to EventType):

Type	Description
INSTITUTION_FACTION_SHIFT	Hegemonic fraction changed within an institution.
INSTITUTION_REPRODUCTION	Institution spawned a replacement Organization.
INSTITUTION_BONAPARTIST_MODE	Bonapartist threshold crossed.

Graph Integration

Institutions are stored on WorldState and participate in the to_graph()/from_graph() round-trip:

from babylon.models.world_state import WorldState

world = WorldState(
    tick=0,
    institutions={"doj": department_of_justice},
    institution_relations=[doj_fbi_relation],
)

graph = world.to_graph()
# graph.nodes["doj"]["_node_type"] == "institution"

reconstructed = WorldState.from_graph(graph, tick=0)
assert isinstance(reconstructed.institutions["doj"], Institution)

to_graph() creates HOUSES edges from each institution to its housed_org_ids.

frozenset handling: model_dump() converts frozenset to list. from_graph() converts back to frozenset for legal_authorities and jurisdiction fields.

InstitutionDefines

Tunable parameters in GameDefines.institution:

Parameter	Default	Description
alpha_smoothing_rate	0.05	[S] Per-call smoothing rate for factional balance shifts.
bonapartist_threshold	0.4	[S] BONAPARTIST weight above which Bonapartist mode triggers.
bonapartist_exclusion_threshold	0.35	[S] Other fractions must be below this for Bonapartist mode.
default_action_modifiers	(see below)	[S] Default action cost modifiers per ApparatusType.

Default action modifiers:

Apparatus Type	Modifiers (ActionType -> multiplier)
rsa_executive	propagandize: 0.5, repress: 0.8, educate: 1.5
rsa_police	repress: 0.6, surveil: 0.7, educate: 2.0
rsa_judicial	surveil: 0.5, repress: 1.2
rsa_military	repress: 0.4, attack_infrastructure: 0.5
rsa_carceral	repress: 0.5, educate: 2.5
isa_educational	educate: 0.7, recruit: 0.8, repress: 2.0
isa_religious	educate: 0.8, recruit: 0.7, repress: 2.5
isa_family	educate: 0.9, recruit: 1.5
isa_communications	propagandize: 0.5, agitate: 0.6, repress: 2.0
isa_cultural	educate: 0.8, propagandize: 0.7, repress: 2.0
isa_legal	(none)
isa_political	(none)
economic_productive	employ: 0.5, fundraise: 0.7, repress: 1.5
economic_financial	fundraise: 0.4, employ: 0.8
economic_extractive	fundraise: 0.5, attack_infrastructure: 0.8

Deprecation Notes

The Organization.is_institution and Organization.institutional_persistence fields (Feature 031) are deprecated. Use Institution.formalization_level and Institution.institutional_inertia instead. Constructing an Organization with these fields set emits DeprecationWarning.

The legacy JSON Schema at src/babylon/schemas/entities/institution.schema.json is superseded by the Pydantic Institution model and will be removed in a future version.

See Also

• The Institution Model – Why institutions exist as a separate layer

• Organization Reference – Organization Base Model reference

• Data Models Reference – SocialClass, Territory, and graph structure

• State Apparatus AI (Feature 039) – State Apparatus AI reference

• OODA Loop System Reference – OODA Loop System reference

• babylon.institution – Pure function source code

• babylon.models.entities.institution – Entity model source code