babylon.models.entities.state_apparatus_ai

State Apparatus AI entity models (Feature 039).

Defines entity models for the state-as-adversary system: - FactionBalance: Power distribution among ruling-class factions - StateBudget: Fiscal constraint on state action - StateAction: State verb execution instance - LegalFramework: Active legislation modifying game rules - VERB_CHILDREN: Parent-child verb hierarchy mapping

All models are frozen (immutable) Pydantic BaseModels.

See also

specs/039-state-apparatus-ai/data-model.md: Entity definitions. babylon.models.entities.attention_thread: AttentionThread, SparrowAnalysis.

Module Attributes

VERB_CHILDREN	Source of truth for hierarchy validation.
TOP_LEVEL_VERBS	Set of top-level verbs (keys of VERB_CHILDREN).
ALL_SUB_VERBS	Set of all sub-verbs (union of all VERB_CHILDREN values).
VALID_LAW_TYPES	Valid law types for LegalFramework.

Functions

get_parent_verb(sub_verb)

Look up the parent verb of a sub-verb.

Classes

FactionBalance(**data)	Power distribution among ruling-class factions (Feature 039).
LegalFramework(**data)	Active legislation modifying game rules in a jurisdiction (Feature 039).
StateAction(**data)	State verb execution instance (Feature 039).
StateBudget(**data)	State budget constraint for verb execution (Feature 039).

babylon.models.entities.state_apparatus_ai.VERB_CHILDREN: dict[StateActionType, frozenset[StateActionType]] = {StateActionType.ADMINISTER: frozenset({StateActionType.AUDIT, StateActionType.FUND, StateActionType.LEGISLATE, StateActionType.REVOKE, StateActionType.STAFF}), StateActionType.CO_OPT: frozenset({StateActionType.BRIBE, StateActionType.DIVIDE, StateActionType.INCORPORATE, StateActionType.PROPAGANDIZE}), StateActionType.DEVELOP: frozenset({StateActionType.DISPLACE, StateActionType.INVEST, StateActionType.NEGLECT, StateActionType.REZONE}), StateActionType.REPRESS: frozenset({StateActionType.INFILTRATE, StateActionType.LIQUIDATE, StateActionType.PROSECUTE, StateActionType.RAID, StateActionType.SURVEIL}), StateActionType.RESEARCH: frozenset({StateActionType.DEPLOY_TECH, StateActionType.PURSUE_TECH}), StateActionType.WITHDRAW: frozenset({StateActionType.SCORCHED_EARTH, StateActionType.STRATEGIC_WITHDRAWAL, StateActionType.TACTICAL_RETREAT})}

Source of truth for hierarchy validation. Each top-level verb maps to its valid sub-verbs. Used by StateAction model validator.

babylon.models.entities.state_apparatus_ai.TOP_LEVEL_VERBS: frozenset[StateActionType] = frozenset({StateActionType.ADMINISTER, StateActionType.CO_OPT, StateActionType.DEVELOP, StateActionType.REPRESS, StateActionType.RESEARCH, StateActionType.WITHDRAW})

Set of top-level verbs (keys of VERB_CHILDREN).

babylon.models.entities.state_apparatus_ai.ALL_SUB_VERBS: frozenset[StateActionType] = frozenset({StateActionType.AUDIT, StateActionType.BRIBE, StateActionType.DEPLOY_TECH, StateActionType.DISPLACE, StateActionType.DIVIDE, StateActionType.FUND, StateActionType.INCORPORATE, StateActionType.INFILTRATE, StateActionType.INVEST, StateActionType.LEGISLATE, StateActionType.LIQUIDATE, StateActionType.NEGLECT, StateActionType.PROPAGANDIZE, StateActionType.PROSECUTE, StateActionType.PURSUE_TECH, StateActionType.RAID, StateActionType.REVOKE, StateActionType.REZONE, StateActionType.SCORCHED_EARTH, StateActionType.STAFF, StateActionType.STRATEGIC_WITHDRAWAL, StateActionType.SURVEIL, StateActionType.TACTICAL_RETREAT})

Set of all sub-verbs (union of all VERB_CHILDREN values).

babylon.models.entities.state_apparatus_ai.get_parent_verb(sub_verb)

Look up the parent verb of a sub-verb.

Parameters:

sub_verb (StateActionType) – A StateActionType that may be a sub-verb.

Return type:

StateActionType | None

Returns:

The top-level parent verb, or None if the input is itself a top-level verb or not found in any parent’s children.

class babylon.models.entities.state_apparatus_ai.FactionBalance(**data)

Bases: BaseModel

Power distribution among ruling-class factions (Feature 039).

The weight vector determines the state’s objective function for verb selection. Shifts based on player actions (FR-C04) and material conditions (FR-C05). Fascist convergence is detected when specific threshold conditions hold (FR-C06).

Primitive state: finance_capital, security_state, settler_populist, stability, legitimacy (stored). Derived state: dominant_faction (computed). Constitution II.2.

Parameters:

• finance_capital (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

• security_state (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

• settler_populist (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

• stability (Annotated[float, Ge(ge=0.0), Le(le=1.0), AfterValidator(func=~babylon.utils.math.quantize)])

• legitimacy (Annotated[float, Ge(ge=0.0), Le(le=1.0), AfterValidator(func=~babylon.utils.math.quantize)])

finance_capital

Weight of Finance-Capital faction [0.0, 1.0].

security_state

Weight of Security-State faction [0.0, 1.0].

settler_populist

Weight of Settler-Populist faction [0.0, 1.0].

stability

How stable the current balance is [0=turbulent, 1=settled].

legitimacy

Overall state legitimacy [0=delegitimized, 1=fully legitimate].

Reference: FR-C02, R-003.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

finance_capital: float

security_state: float

settler_populist: float

stability: Probability

legitimacy: Probability

property dominant_faction: StateFaction

Faction with highest weight.

class babylon.models.entities.state_apparatus_ai.StateBudget(**data)

Bases: BaseModel

State budget constraint for verb execution (Feature 039).

Revenue derives from tax revenue, federal transfers, and imperial rent pool. Allocation across verb categories is computed each tick as the dot product of faction weights and faction verb preferences.

Budget is finite – the fundamental constraint making state behavior strategic rather than omnipotent.

Parameters:

• revenue (Annotated[float, Ge(ge=0)])

• available (Annotated[float, Ge(ge=0)])

• allocated (dict[StateActionType, float])

• imperial_rent_pool (Annotated[float, Ge(ge=0)])

revenue

Total income this tick.

available

Unallocated funds remaining this tick.

allocated

Budget allocated per top-level verb category.

imperial_rent_pool

Discretionary capacity from imperial rent.

Reference: FR-D05, R-004.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

revenue: float

available: float

allocated: dict[StateActionType, float]

imperial_rent_pool: float

class babylon.models.entities.state_apparatus_ai.StateAction(**data)

Bases: BaseModel

State verb execution instance (Feature 039).

Parallel to the player Action model (Feature 032) but with different resource profiles. Budget constrains non-REPRESS verbs; attention threads constrain REPRESS verbs (Assumption A-004).

Parameters:

• verb (StateActionType)

• sub_verb (StateActionType)

• target_id (str | None)

• budget_cost (Annotated[float, Ge(ge=0)])

• thread_cost (Annotated[int, Ge(ge=0)])

• legitimacy_cost (float)

• faction_alignment (StateFaction)

• parameters (dict[str, Any])

verb

Top-level verb category.

sub_verb

Specific sub-verb within the verb category.

target_id

Target entity ID (None for self-targeting).

budget_cost

Budget consumed by this action.

thread_cost

Attention threads required (for REPRESS verbs).

legitimacy_cost

Legitimacy impact (negative = delegitimizing).

faction_alignment

Which faction benefits from this action.

parameters

Sub-verb-specific parameters.

Reference: FR-B01 through FR-B11, FR-D05, R-005.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

verb: StateActionType

sub_verb: StateActionType

target_id: str | None

budget_cost: float

thread_cost: int

legitimacy_cost: float

faction_alignment: StateFaction

parameters: dict[str, Any]

babylon.models.entities.state_apparatus_ai.VALID_LAW_TYPES: frozenset[str] = frozenset({'CRIMINALIZATION', 'EMERGENCY_POWERS', 'LABOR_RESTRICTION', 'SURVEILLANCE_EXPANSION', 'TAX_INCENTIVE', 'ZONING_CHANGE'})

Valid law types for LegalFramework.

class babylon.models.entities.state_apparatus_ai.LegalFramework(**data)

Bases: BaseModel

Active legislation modifying game rules in a jurisdiction (Feature 039).

Created by LEGISLATE sub-action, removed by REVOKE sub-action. No automatic expiry – legislation persists until explicitly revoked. Revocation carries its own legitimacy cost/gain depending on context.

Parameters:

• framework_id (Annotated[str, MinLen(min_length=1)])

• law_type (str)

• scope (str)

• severity (Annotated[float, Ge(ge=0.0), Le(le=1.0), AfterValidator(func=~babylon.utils.math.quantize)])

• effects (dict[str, float])

• created_tick (Annotated[int, Ge(ge=0)])

• creating_apparatus_id (Annotated[str, MinLen(min_length=1)])

framework_id

Unique framework identifier.

law_type

Legislation category.

scope

Jurisdiction scope (JurisdictionLevel value).

severity

How extreme the legislation is [0=mild, 1=extreme].

effects

Rule modifications applied (varies by law_type).

created_tick

Tick when enacted.

creating_apparatus_id

Apparatus that enacted this.

Reference: FR-B09, R-011.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

framework_id: str

law_type: str

scope: str

severity: Probability

effects: dict[str, float]

created_tick: int

creating_apparatus_id: str