Weather recourse API

Weather- and outage-aware annual recourse for the rolling policy.

The policy observes each year’s cost, hours, and capacity before committing actions. The forecast-aware case plans against an independent synthetic calendar and executes under the actual calendar. The calendar-aware case observes the actual calendar and defers unschedulable actions until every retained action fits it. These are calendar policies, not forecast products or stochastic dynamic programs.

class brushline.strategic.weather_recourse.WeatherCalendarConfig(*, window_days: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=366)] = 75, outage_days: list[int] = <factory>, weather_probability: Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = 0.2, travel_hours: Annotated[float, ~annotated_types.Ge(ge=0)] = 0.5, seed: int = 7)[source]

Bases: BaseModel

Assumed per-year weather and outage calendar.

model_config = {'extra': 'forbid', 'frozen': True}

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

class brushline.strategic.weather_recourse.WeatherCaseSummary(*, name: Literal['calendar-naive', 'forecast-aware', 'calendar-aware'], budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], completion_band: RecourseBand, retained_scope_band: RecourseBand, risk_band: RecourseBand, cost_band: RecourseBand, hours_band: RecourseBand, mean_deferred_actions: Annotated[float, Ge(ge=0)], mean_resource_deferred_actions: Annotated[float, Ge(ge=0)], mean_calendar_deferred_actions: Annotated[float, Ge(ge=0)], mean_deferred_hours: Annotated[float, Ge(ge=0)], mean_unscheduled_hours: Annotated[float, Ge(ge=0)], mean_risk_loss: Annotated[float, Ge(ge=0)], mean_extra_crew_days: Annotated[float, Ge(ge=0)] = 0, mean_extra_machine_days: Annotated[float, Ge(ge=0)] = 0, mean_resource_cost: Annotated[float, Ge(ge=0)] = 0, total_cost_band: RecourseBand | None = None)[source]

Bases: BaseModel

Summary for calendar-naive or calendar-aware execution.

model_config = {'extra': 'forbid', 'frozen': True}

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

exception brushline.strategic.weather_recourse.WeatherRecourseError[source]

Bases: ValueError

Raised when weather-recourse inputs are inconsistent.

class brushline.strategic.weather_recourse.WeatherRecourseResult(*, schema_version: Literal['brushline.weather-recourse.v1'] = 'brushline.weather-recourse.v1', instance_id: str, episodes: Annotated[int, Ge(ge=1)], seed: int, years: list[int], solver: Literal['exact', 'heuristic'], lookahead_years: Annotated[int, Ge(ge=1)], calendar: WeatherCalendarConfig, cases: list[WeatherCaseSummary], created_utc: datetime)[source]

Bases: BaseModel

Calendar-naive, forecast-aware, and observed-calendar-aware comparison.

model_config = {'extra': 'forbid', 'frozen': True}

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

brushline.strategic.weather_recourse.evaluate_weather_recourse(*, instance_id: str, plan: StatefulPlan, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], crews: list[ShiftCrew], machines: list[ShiftMachine], config: StatefulConfig | None = None, episodes: int = 20, seed: int = 7, solver: Literal['exact', 'heuristic'] = 'exact', heuristic_iterations: int = 100, lookahead_years: int = 2, calendar: WeatherCalendarConfig | None = None, created_utc: datetime | None = None) → WeatherRecourseResult[source]

Compare calendar-naive, forecast-aware, and calendar-aware annual recourse.