Python API Reference

class StrictBaseModel(BaseModel):
    """Base class enabling strict Pydantic v2 validation for all nested fields."""

    model_config = ConfigDict(strict=True)

class PlantComponentSchema(StrictBaseModel):
    """Pydantic schema for the Plant ECS component."""

    entity_id: int = Field(..., description="Unique ECS entity identifier.")
    species_id: SpeciesId = Field(..., description="Flora species index [0, MAX_FLORA_SPECIES).")
    x: int = Field(..., ge=0, description="Grid x-coordinate.")
    y: int = Field(..., ge=0, description="Grid y-coordinate.")
    energy: float = Field(..., ge=0.0, description="[Absolute] Current energy reserve (E_i,j).")
    max_energy: float = Field(..., gt=0.0, description="[Absolute] Species-specific energy capacity (E_max).")
    base_energy: float = Field(..., gt=0.0, description="[Absolute] Initial energy E_i,j(0).")
    growth_rate: float = Field(
        ..., ge=0.0, description="[% Rate] Per-tick growth rate r_i,j. Expressed as a fraction (e.g. 0.05 = 5%)."
    )
    survival_threshold: float = Field(..., ge=0.0, description="[Absolute] Minimum energy B_i,j before death.")
    reproduction_interval: int = Field(..., gt=0, description="[Ticks] Ticks between reproduction attempts (T_i).")
    seed_min_dist: float = Field(..., ge=0.0, description="[Absolute] Minimum seed dispersal distance d_min.")
    seed_max_dist: float = Field(..., gt=0.0, description="[Absolute] Maximum seed dispersal distance d_max.")
    seed_energy_cost: float = Field(..., ge=0.0, description="[Absolute] Energy cost per reproduction event.")
    camouflage: bool = Field(default=False, description="[Flag] Constitutive gradient attenuation flag.")
    camouflage_factor: float = Field(default=1.0, ge=0.0, le=1.0, description="[%] Gradient multiplier (0.0 to 1.0).")
    last_reproduction_tick: int = Field(default=0, description="[Ticks] Last tick of reproduction.")
    apparent_nutrition_factor: float = Field(
        default=1.0, ge=0.0, le=1.0, description="[%] Current stress-induced nutrient discount (0.0 to 1.0)."
    )
    withdrawal_ticks_remaining: int = Field(
        default=0, ge=0, description="[Ticks] Ticks until apparent_nutrition_factor resets to 1.0."
    )

class SubstanceComponentSchema(StrictBaseModel):
    """Pydantic schema for a Substance (signal or toxin) ECS component."""

    entity_id: int = Field(..., description="Unique ECS entity identifier.")
    substance_id: SubstanceId = Field(..., description="Substance layer index.")
    owner_plant_id: int = Field(..., description="[ID] ECS entity id of the producing plant.")
    is_toxin: bool = Field(default=False, description="[Flag] True for toxins, False for signals.")
    synthesis_remaining: int = Field(default=0, ge=0, description="[Ticks] Ticks before substance becomes active.")
    active: bool = Field(default=False, description="[Flag] Whether the substance is currently active.")
    aftereffect_ticks: int = Field(default=0, ge=0, description="[Ticks] Remaining aftereffect duration T_k.")
    lethal: bool = Field(default=False, description="[Flag] Lethal toxin flag.")
    lethality_rate: float = Field(default=0.0, ge=0.0, description="[Absolute] Individuals eliminated per tick.")
    repellent: bool = Field(default=False, description="[Flag] Repellent toxin flag.")
    repellent_walk_ticks: int = Field(default=0, ge=0, description="[Ticks] Random-walk duration k on repel trigger.")
    energy_cost_per_tick: float = Field(
        default=0.0, ge=0.0, description="[Absolute] Energy cost drained from the owner plant per active tick."
    )
    irreversible: bool = Field(
        default=False,
        description="Whether activation is irreversible once the substance becomes active.",
    )

class SwarmComponentSchema(StrictBaseModel):
    """Pydantic schema for the Herbivore Swarm ECS component."""

    entity_id: int = Field(..., description="Unique ECS entity identifier.")
    species_id: HerbivoreId = Field(..., description="Herbivore species index [0, MAX_HERBIVORE_SPECIES).")
    x: int = Field(..., ge=0, description="Grid x-coordinate.")
    y: int = Field(..., ge=0, description="Grid y-coordinate.")
    population: int = Field(..., gt=0, description="[Absolute] Current swarm head-count n(t).")
    initial_population: int = Field(..., gt=0, description="[Absolute] Initial population n(0) for mitosis.")
    energy: float = Field(..., ge=0.0, description="[Absolute] Current energy reserve.")
    energy_min: float = Field(..., gt=0.0, description="[Absolute] Minimum energy per individual E_min(e_h).")
    velocity: int = Field(..., gt=0, description="[Ticks] Ticks between moves. Higher is slower.")
    consumption_rate: float = Field(..., gt=0.0, description="[Absolute] Per-tick consumption scalar η(C_i).")
    energy_upkeep_per_individual: float = Field(
        default=0.05,
        ge=0.0,
        description="[Absolute] Per-individual metabolic upkeep scalar applied each tick.",
    )
    split_population_threshold: int = Field(
        default=10,
        gt=0,
        description="[Absolute] Explicit mitosis population threshold.",
    )
    repelled: bool = Field(default=False, description="Currently repelled by toxin.")
    repelled_ticks_remaining: int = Field(default=0, description="Ticks remaining in repelled random-walk.")

class AllOfConditionSchema(StrictBaseModel):
    """Boolean AND over nested activation predicates."""

    kind: Literal["all_of"] = "all_of"
    conditions: list[ConditionNode] = Field(
        ...,
        min_length=1,
        description="All child predicates must evaluate to true.",
    )

class AnyOfConditionSchema(StrictBaseModel):
    """Boolean OR over nested activation predicates."""

    kind: Literal["any_of"] = "any_of"
    conditions: list[ConditionNode] = Field(
        ...,
        min_length=1,
        description="At least one child predicate must evaluate to true.",
    )

class EnvironmentalSignalConditionSchema(StrictBaseModel):
    """Leaf predicate requiring a minimum ambient signal concentration at the owner's cell."""

    kind: Literal["environmental_signal"] = "environmental_signal"
    signal_id: SubstanceId = Field(..., description="Signal layer identifier to read from the environment.")
    min_concentration: float = Field(
        default=0.01,
        ge=0.0,
        description="Minimum concentration required for this predicate.",
    )

class HerbivorePresenceConditionSchema(StrictBaseModel):
    """Leaf predicate requiring a herbivore species at the owner's cell."""

    kind: Literal["herbivore_presence"] = "herbivore_presence"
    herbivore_species_id: HerbivoreId
    min_herbivore_population: int = Field(
        default=1,
        gt=0,
        description="Minimum co-located herbivore population required for this predicate.",
    )

class SubstanceActiveConditionSchema(StrictBaseModel):
    """Leaf predicate requiring another substance to already be active."""

    kind: Literal["substance_active"] = "substance_active"
    substance_id: SubstanceId = Field(..., description="Active substance required for this predicate.")

class EnvironmentalSignalInitiator(StrictBaseModel):
    """Initiator that triggers when an environmental signal reaches a concentration threshold."""

    type: Literal["environmental_signal"] = "environmental_signal"
    signal_id: int = Field(..., ge=0, description="The substance ID of the environmental signal to monitor.")
    min_concentration: float = Field(
        default=0.01, ge=0.0, description="Minimum concentration threshold in the flow field."
    )
    response_curve: Literal["step", "hill", "logarithmic"] = Field(
        default="step", description="Dose-response curve type: step, hill (sigmoidal kinetics), or logarithmic."
    )
    hill_cooperativity: float = Field(
        default=2.0, gt=0.0, description="Hill cooperativity exponent n controlling dose-response steepness."
    )
    half_saturation: float = Field(
        default=0.05, gt=0.0, description="Semi-saturation constant Kd (concentration where response is 50%)."
    )

class HerbivoreAttackInitiator(StrictBaseModel):
    """Initiator that triggers when a herbivore population reaches a threshold."""

    type: Literal["herbivore_attack"] = "herbivore_attack"
    herbivore_species_id: HerbivoreId
    min_herbivore_population: int = Field(..., gt=0, description="Minimum swarm size n_i,min to trigger the rule.")

class PassiveDefensesSchema(StrictBaseModel):
    """Morphological (passive) defenses of a flora species."""

    mechanical_damage_per_bite: float = Field(
        default=0.0, ge=0.0, description="[Absolute] Thorns/spines damage per feeding event."
    )
    digestibility_modifier: float = Field(
        default=1.0,
        ge=0.0,
        le=1.0,
        description="[%] Lignin/silica calorie discount multiplier (e.g. 0.5 = 50% metabolized).",
    )

class ResourceWithdrawalAction(StrictBaseModel):
    """Action to trigger apparent nutrition withdrawal (stress response)."""

    type: Literal["resource_withdrawal"] = "resource_withdrawal"
    apparent_nutrition_factor: float = Field(
        default=1.0, ge=0.0, le=1.0, description="[%] Multiplier for energy apparent to herbivores and flow field."
    )
    withdrawal_duration: int = Field(
        default=10,
        gt=0,
        description=(
            "[Ticks] Duration of the nutrition withdrawal. It determines how many ticks the apparent "
            "nutrition factor will remain dimmed. Note that the duration is immediately decremented by 1 at the end "
            "of the tick the trigger fires, so a duration of 1 means it recovers on the next tick."
        ),
    )

class SynthesizeSubstanceAction(StrictBaseModel):
    """Action to synthesize a specific chemical substance."""

    type: Literal["synthesize_substance"] = "synthesize_substance"
    substance_id: SubstanceId = Field(..., description="[ID] Substance to synthesise.")
    synthesis_duration: int = Field(..., gt=0, description="[Ticks] Ticks to synthesise T(s_x).")
    is_toxin: bool = Field(default=False, description="[Flag] True for toxins, False for signals.")
    lethal: bool = Field(default=False, description="[Flag] Lethal toxin flag.")
    lethality_rate: float = Field(default=0.0, ge=0.0, description="[Absolute] Individuals eliminated per tick.")
    repellent: bool = Field(default=False, description="[Flag] Repellent toxin flag.")
    repellent_walk_ticks: int = Field(default=0, ge=0, description="[Ticks] Random-walk duration k on repel trigger.")
    energy_cost_per_tick: float = Field(
        default=0.0, ge=0.0, description="[Absolute] Energy drained from the plant per tick while active."
    )
    irreversible: bool = Field(
        default=False,
        description="If true, activation is irreversible: once active, the substance remains active until owner death.",
    )

class TriggerConditionSchema(StrictBaseModel):
    """Trigger condition for defense actions (Interaction Matrix entry).

    Maps an initiator (e.g. herbivore presence, environmental signal) to an action
    that should be executed when the trigger conditions are met.
    """

    model_config = ConfigDict(extra="forbid")

    initiator: TriggerInitiator = Field(..., description="The condition that initiates this rule.")
    aftereffect_ticks: int = Field(
        default=0,
        ge=0,
        description="Aftereffect duration T_k (action effect lingers after trigger ceases).",
    )
    activation_condition: ConditionNode | None = Field(
        default=None,
        description=(
            "Optional nested predicate tree controlling whether the configured action may activate. "
            "Supports explicit all_of/any_of composition over herbivore_presence and substance_active leaves."
        ),
    )
    action: TriggerAction = Field(..., description="The action to perform when triggered.")

    @model_validator(mode="before")
    @classmethod
    def _map_legacy_trigger_fields(cls, data: dict[str, Any]) -> dict[str, Any]:
        """Maps legacy `herbivore_species_id` and `min_herbivore_population` to `initiator`."""
        if isinstance(data, dict) and "initiator" not in data:
            if "herbivore_species_id" in data:
                data["initiator"] = {
                    "type": "herbivore_attack",
                    "herbivore_species_id": data.pop("herbivore_species_id"),
                    "min_herbivore_population": data.pop("min_herbivore_population", 5),
                }
        return data

class DietCompatibilityMatrix(StrictBaseModel):
    """Boolean matrix [herbivore_species, flora_species] indicating edibility."""

    rows: list[list[bool]] = Field(
        ...,
        description=(
            "Outer index = herbivore species id, inner index = flora species id. "
            "True means the herbivore can consume that flora species."
        ),
    )

    @model_validator(mode="after")
    def _validate_shape(self) -> DietCompatibilityMatrix:
        n_herbivore = len(self.rows)
        if n_herbivore > MAX_HERBIVORE_SPECIES:
            raise ValueError(f"DietCompatibilityMatrix has {n_herbivore} rows, max is {MAX_HERBIVORE_SPECIES}.")
        for row in self.rows:
            if len(row) > MAX_FLORA_SPECIES:
                raise ValueError(f"DietCompatibilityMatrix row length {len(row)} exceeds {MAX_FLORA_SPECIES}.")
        return self

class FloraSpeciesParams(StrictBaseModel):
    """Per-species parameters for flora."""

    species_id: SpeciesId
    name: str
    base_energy: float = Field(..., gt=0.0)
    max_energy: float = Field(..., gt=0.0)
    growth_rate: float = Field(..., ge=0.0)
    survival_threshold: float = Field(..., ge=0.0)
    reproduction_interval: int = Field(..., gt=0)
    seed_min_dist: float = Field(default=1.0, ge=0.0)
    seed_max_dist: float = Field(default=3.0, gt=0.0)
    seed_energy_cost: float = Field(default=5.0, ge=0.0)
    seed_drop_height: float = Field(
        default=SEED_DROP_HEIGHT_DEFAULT,
        gt=0.0,
        description=("Approximate seed release height used for wind-flight-time estimation in anemochorous dispersal."),
    )
    seed_terminal_velocity: float = Field(
        default=SEED_TERMINAL_VELOCITY_DEFAULT,
        gt=0.0,
        description=("Approximate seed terminal fall velocity used for wind-driven downwind shift estimation."),
    )
    camouflage: bool = False
    camouflage_factor: float = Field(default=1.0, ge=0.0, le=1.0)
    translocation_rate: float = Field(
        default=0.2, ge=0.0, le=1.0, description="Rate of nutrient translocation during resource withdrawal."
    )
    mycorrhizal_tax_per_link: float = Field(
        default=0.0, ge=0.0, description="Continuous energy maintenance fee deducted per active root link per tick."
    )
    passive_defenses: PassiveDefensesSchema = Field(default_factory=PassiveDefensesSchema)
    triggers: list[TriggerConditionSchema] = Field(default_factory=list, max_length=MAX_SUBSTANCE_TYPES)

class HerbivoreResistancesSchema(StrictBaseModel):
    """Herbivore resistances to passive plant defenses."""

    morphological_adaptation: float = Field(
        default=0.0,
        ge=0.0,
        le=1.0,
        description="[%] Resistance to physical plant defenses like thorns or spines (0.0 to 1.0).",
    )
    chemical_neutralization: float = Field(
        default=0.0, ge=0.0, le=1.0, description="[%] Metabolic ability to neutralize ingested toxins (0.0 to 1.0)."
    )
    digestive_efficiency: float = Field(
        default=1.0,
        ge=0.0,
        description="[%] Ability to extract calories from tough plant matter (0.0+ multiplier).",
    )

class HerbivoreSpeciesParams(StrictBaseModel):
    """Per-species parameters for herbivore swarms."""

    species_id: HerbivoreId
    name: str
    energy_min: float = Field(..., gt=0.0)
    velocity: int = Field(..., gt=0)
    consumption_rate: float = Field(..., gt=0.0)
    handling_time: float = Field(
        default=0.0,
        ge=0.0,
        description="Handling time per calorie eaten (Holling Type II functional response). 0.0 retains linear intake.",
    )
    behavior_paradigm: SwarmBehaviorParadigm = Field(
        default="macro_swarm",
        description="Behavioral paradigm governing movement and foraging kinetics.",
    )
    reproduction_energy_divisor: float = Field(
        default=1.0,
        gt=0.0,
        validation_alias=AliasChoices("reproduction_energy_divisor", "reproduction_divisor"),
        description="Denominator for φ(e_h,t) = floor(R(C_i,t) / E_min(e_h)).",
    )
    energy_upkeep_per_individual: float = Field(
        default=0.05,
        ge=0.0,
        description="Per-individual metabolic upkeep scalar applied every interaction tick.",
    )
    resistances: HerbivoreResistancesSchema = Field(default_factory=HerbivoreResistancesSchema)
    split_population_threshold: int = Field(
        default=10,
        gt=0,
        description="Explicit population threshold for mitosis.",
    )

class BandedPlacement(StrictBaseModel):
    """Entities placed in dense lines/stripes."""

    type: Literal["banded"] = "banded"
    band_count: int = Field(..., ge=1)
    orientation: Literal["horizontal", "vertical"] = "horizontal"

class ClusteredPlacement(StrictBaseModel):
    """Groups of entities clustered around random centroids."""

    type: Literal["clustered"] = "clustered"
    cluster_count: int = Field(..., ge=1)
    variance: float = Field(..., gt=0.0)

class InitialPlantPlacement(StrictBaseModel):
    """Single plant to place at simulation start."""

    species_id: SpeciesId
    x: int = Field(..., ge=0)
    y: int = Field(..., ge=0)
    energy: float = Field(..., gt=0.0)

class InitialSwarmPlacement(StrictBaseModel):
    """Single swarm to place at simulation start."""

    species_id: HerbivoreId
    x: int = Field(..., ge=0)
    y: int = Field(..., ge=0)
    population: int = Field(..., gt=0)
    energy: float = Field(..., gt=0.0)

class UniformPlacement(StrictBaseModel):
    """Randomly scattered entities."""

    type: Literal["uniform"] = "uniform"
    density: float = Field(..., ge=0.0, le=1.0)

class SimulationConfig(StrictBaseModel):
    """Complete simulation configuration payload (REST /api/scenario/load body)."""

    grid_width: int = Field(default=40, ge=1, le=200)
    grid_height: int = Field(default=40, ge=1, le=200)
    max_ticks: int = Field(default=1000, gt=0)
    tick_rate_hz: float = Field(default=10.0, gt=0.0, description="WebSocket stream tick rate.")

    num_signals: int = Field(default=4, ge=1, le=MAX_SUBSTANCE_TYPES)
    num_toxins: int = Field(default=4, ge=1, le=MAX_SUBSTANCE_TYPES)

    wind_x: float = Field(default=0.0, description="Initial wind vector x-component.")
    wind_y: float = Field(default=0.0, description="Initial wind vector y-component.")

    flora_species: list[FloraSpeciesParams] = Field(..., min_length=1, max_length=MAX_FLORA_SPECIES)
    herbivore_species: list[HerbivoreSpeciesParams] = Field(..., min_length=1, max_length=MAX_HERBIVORE_SPECIES)
    diet_matrix: DietCompatibilityMatrix

    placement_mode: Literal["manual", "procedural"] = "manual"
    flora_placement_strategy: PlacementStrategy | None = None
    herbivore_placement_strategy: PlacementStrategy | None = None

    initial_plants: list[InitialPlantPlacement] = Field(default_factory=list)
    initial_swarms: list[InitialSwarmPlacement] = Field(default_factory=list)

    # Symbiotic network settings
    mycorrhizal_inter_species: bool = Field(default=False, description="Allow inter-species root connections.")
    mycorrhizal_connection_cost: float = Field(default=1.0, ge=0.0, description="Energy cost to establish a root link.")
    mycorrhizal_growth_interval_ticks: int = Field(
        default=8,
        ge=1,
        le=256,
        description=("Ticks between mycorrhizal growth attempts. At most one new root link is formed per interval."),
    )
    mycorrhizal_signal_velocity: int = Field(default=1, gt=0, description="Signal transfer speed t_g (ticks per hop).")

    # Termination conditions
    z2_flora_species_extinction: int = Field(
        default=-1, description="Halt when this flora species id goes extinct (-1 = disabled)."
    )
    z4_herbivore_species_extinction: int = Field(
        default=-1,
        description="Halt when this herbivore species id goes extinct (-1 = disabled).",
    )
    z6_max_total_flora_energy: float = Field(
        default=-1.0, description="Halt when total flora energy exceeds this value (-1 = disabled)."
    )
    z7_max_total_herbivore_population: int = Field(
        default=-1,
        description="Halt when total herbivore population exceeds this value (-1 = disabled).",
    )

    # Configurable Chemotaxis and Navigation Parameters
    chemotaxis_alpha: float = Field(
        default=1.0,
        ge=0.0,
        description="Weighting coefficient for botanical attractants.",
        json_schema_extra={
            "ui_category": "Chemotaxis & Navigation",
            "sensitivity": "High Impact",
            "effects": ("Increasing this makes swarms more desperate to reach food, potentially ignoring toxins."),
        },
    )
    chemotaxis_beta: float = Field(
        default=1.0,
        ge=0.0,
        description="Weighting coefficient for toxic repellents.",
        json_schema_extra={
            "ui_category": "Chemotaxis & Navigation",
            "sensitivity": "High Impact",
            "effects": (
                "Increasing this makes swarms extremely averse to toxins, "
                "potentially starving before crossing a defensive perimeter."
            ),
        },
    )
    chemotaxis_decay: float = Field(
        default=0.6,
        ge=0.0,
        le=1.0,
        description="Propagation decay factor for the flow field.",
        json_schema_extra={
            "ui_category": "Chemotaxis & Navigation",
            "sensitivity": "Advanced Tuning",
            "effects": (
                "Higher values allow the chemotaxis gradient to propagate further distances, "
                "effectively increasing the sensory horizon of swarms."
            ),
        },
    )
    chemotaxis_truncate_threshold: float = Field(
        default=1e-4,
        ge=0.0,
        description="Subnormal truncation threshold.",
        json_schema_extra={
            "ui_category": "Chemotaxis & Navigation",
            "sensitivity": "Advanced Math Tuning",
            "effects": (
                "Prevents float denormalization slowdowns in the Numba JIT solver "
                "by zeroing out infinitesimal gradients."
            ),
        },
    )

    # Configurable diffusion / emission constants (runtime-overridable via DSE)
    signal_decay_factor: float = Field(
        default=0.85,
        gt=0.0,
        le=1.0,
        description=(
            "Per-tick airborne signal retention after Gaussian diffusion (0.0-1.0). "
            "1.0 = no decay; values closer to 0.0 cause total dissipation each tick. "
            "Exposed in the UI as Signal Decay (%)."
        ),
    )
    substance_emit_rate: float = Field(
        default=0.1,
        gt=0.0,
        le=1.0,
        description=(
            "Concentration increment added to a signal or toxin layer per tick "
            "when an active SubstanceComponent emits into the environment. "
            "Exposed in the UI as Substance Emit Rate (%)."
        ),
    )

    # Replay backend selection
    replay_backend: str = Field(
        default="zarr",
        description="Replay storage backend.",
        pattern="^zarr$",
    )

    @model_validator(mode="after")
    def _validate_species_ids(self) -> SimulationConfig:
        flora_ids = {s.species_id for s in self.flora_species}
        herbivore_ids = {s.species_id for s in self.herbivore_species}
        for plant_placement in self.initial_plants:
            if plant_placement.species_id not in flora_ids:
                raise ValueError(
                    f"InitialPlantPlacement references unknown flora species {plant_placement.species_id}."
                )
        for swarm_placement in self.initial_swarms:
            if swarm_placement.species_id not in herbivore_ids:
                raise ValueError(
                    f"InitialSwarmPlacement references unknown herbivore species {swarm_placement.species_id}."
                )
        return self

class BatchJobState(StrictBaseModel):
    """Runtime state record for a single Monte Carlo batch simulation job.

    Each batch job corresponds to ``N`` independent simulation runs dispatched
    to a :class:`concurrent.futures.ProcessPoolExecutor`. Progress is tracked as
    completed run count relative to the total, and the final aggregate summary is
    persisted to disk for retrieval via the ledger and view endpoints.

    Attributes:
        job_id: Universally unique identifier assigned at job creation.
        status: Lifecycle state of the job.
        completed: Number of runs that have completed (successfully or not).
        total: Total number of runs requested.
        scenario_name: Display label derived from the source scenario config.
        started_at: ISO-8601 timestamp of job creation.
        finished_at: ISO-8601 timestamp of completion, or ``None`` if pending.
        max_ticks: Maximum tick count per individual run.

    """

    job_id: str
    status: Literal["queued", "running", "done", "failed"]
    completed: int = 0
    total: int = 1
    scenario_name: str = "unnamed"
    started_at: str = ""
    finished_at: str | None = None
    max_ticks: int = 500

class BatchStartPayload(StrictBaseModel):
    """HTTP request payload for initiating a Monte Carlo batch simulation job.

    Encapsulates the simulation scenario and batch execution parameters
    submitted via ``POST /api/batch/start``. The ``scenario`` field accepts a
    complete :class:`SimulationConfig` that overrides the current server-side
    draft, enabling fully reproducible parameterized batch studies.

    Attributes:
        runs: Number of independent simulation runs to execute in parallel.
        max_ticks: Maximum simulation tick count per run.
        scenario_name: Optional display label for the ledger.

    """

    runs: int = Field(default=10, ge=1, le=256, description="Number of parallel Monte Carlo runs.")
    max_ticks: int = Field(default=500, gt=0, description="Maximum ticks per run.")
    scenario_name: str = Field(default="", description="Optional display label for the job ledger.")

class SimulationStatusResponse(StrictBaseModel):
    """Response model for simulation state queries."""

    tick: int
    tick_rate_hz: float
    running: bool
    paused: bool
    terminated: bool
    termination_reason: str | None = None

class TickRateUpdatePayload(StrictBaseModel):
    """REST payload for dynamically updating live simulation tick speed."""

    tick_rate_hz: float = Field(default=10.0, gt=0.0)

class WindUpdatePayload(StrictBaseModel):
    """REST payload for dynamically updating wind vectors."""

    wind_x: float
    wind_y: float

class DSEStreamManager:
    """Connection manager for real-time Design Space Exploration UI updates.

    Broadcasts NSGA-II Pareto Front generation payloads directly to the active
    HTMX client connection over ``/ws/dse/stream``.
    """

    def __init__(self) -> None:
        """Initialise the DSE stream connection roster."""
        self.active_dse_connections: list[WebSocket] = []

    async def connect_dse(self, websocket: WebSocket) -> None:
        """Accept and register a new DSE websocket connection.

        Args:
            websocket: The WebSocket connection to establish.
        """
        await websocket.accept()
        self.active_dse_connections.append(websocket)
        logger.info("DSE client connected (active=%d)", len(self.active_dse_connections))

    def disconnect_dse(self, websocket: WebSocket) -> None:
        """Remove a DSE websocket connection.

        Args:
            websocket: The WebSocket connection to terminate.
        """
        if websocket in self.active_dse_connections:
            self.active_dse_connections.remove(websocket)
            logger.info("DSE client disconnected (active=%d)", len(self.active_dse_connections))

    async def broadcast_dse(self, payload: dict[str, Any]) -> None:
        """Broadcast a JSON DSE payload to all connected clients.

        Args:
            payload: JSON-serializable dictionary containing generation metrics.

        """
        disconnected: list[WebSocket] = []
        for connection in self.active_dse_connections:
            try:
                await connection.send_json(payload)
            except Exception as e:
                logger.warning("DSE client failed receive, dropping connection. %s", str(e))
                disconnected.append(connection)

        for connection in disconnected:
            self.disconnect_dse(connection)