Two-stage recourse API
Two-stage first-year recourse for a fixed stateful plan.
The first-stage plan is fixed. After annual cost, productivity, and capacity factors are observed, the second stage defers whole actions by lowest first-year risk reduction per hour until the annual budget and crew-hour capacity are satisfied. This is an operational recourse evaluation, not a stochastic dynamic program.
- class brushline.strategic.two_stage.MultiRecourseOutcome(*, index: Annotated[int, Ge(ge=0)], static_cost: Annotated[float, Ge(ge=0)], static_hours: Annotated[float, Ge(ge=0)], static_budget_exceeded: bool, static_capacity_shortfall: bool, static_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], static_completion: Annotated[float, Ge(ge=0), Le(le=1)], recourse_cost: Annotated[float, Ge(ge=0)], recourse_hours: Annotated[float, Ge(ge=0)], recourse_budget_exceeded: bool, recourse_capacity_shortfall: bool, recourse_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], recourse_completion: Annotated[float, Ge(ge=0), Le(le=1)], deferred_actions: Annotated[int, Ge(ge=0)], deferred_hours: Annotated[float, Ge(ge=0)], risk_loss: Annotated[float, Ge(ge=0)], years: list[RecourseYear])[source]
Bases:
BaseModelOne multi-year scenario outcome.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.two_stage.MultiRecourseResult(*, schema_version: Literal['brushline.two-stage-multi.v1'] = 'brushline.two-stage-multi.v1', instance_id: str, episodes: Annotated[int, Ge(ge=1)], seed: int, years: list[int], first_stage_actions: Annotated[int, Ge(ge=0)], annual_budget: Annotated[float, Ge(ge=0)], annual_capacity_hours: Annotated[float, Ge(ge=0)], static_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], static_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], recourse_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], recourse_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], static_cost_band: RecourseBand, recourse_cost_band: RecourseBand, static_hours_band: RecourseBand, recourse_hours_band: RecourseBand, static_risk_band: RecourseBand, recourse_risk_band: RecourseBand, static_completion_band: RecourseBand, recourse_completion_band: RecourseBand, mean_deferred_actions: float, mean_deferred_hours: float, mean_risk_loss: float, outcomes: list[MultiRecourseOutcome], created_utc: datetime)[source]
Bases:
BaseModelMulti-year annual operational recourse summary.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.two_stage.RecourseBand(*, p10: float, p50: float, p90: float, mean: float)[source]
Bases:
BaseModelP10/P50/P90 band.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.two_stage.RecourseFactors(*, cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)])[source]
Bases:
BaseModelObserved first-year factors.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.two_stage.RecourseOutcome(*, index: Annotated[int, Ge(ge=0)], factors: RecourseFactors, static_cost: Annotated[float, Ge(ge=0)], static_hours: Annotated[float, Ge(ge=0)], static_budget_exceeded: Annotated[float, Ge(ge=0)], static_capacity_shortfall: Annotated[float, Ge(ge=0)], static_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], static_completion: Annotated[float, Ge(ge=0), Le(le=1)], recourse_cost: Annotated[float, Ge(ge=0)], recourse_hours: Annotated[float, Ge(ge=0)], recourse_budget_exceeded: Annotated[float, Ge(ge=0)], recourse_capacity_shortfall: Annotated[float, Ge(ge=0)], recourse_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], recourse_completion: Annotated[float, Ge(ge=0), Le(le=1)], deferred_actions: Annotated[int, Ge(ge=0)], deferred_hours: Annotated[float, Ge(ge=0)], risk_loss: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelStatic versus recourse result for one scenario.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.two_stage.RecourseYear(*, year: int, actions: Annotated[int, Ge(ge=0)], static_cost: Annotated[float, Ge(ge=0)], static_hours: Annotated[float, Ge(ge=0)], static_budget_exceeded: Annotated[float, Ge(ge=0)], static_capacity_shortfall: Annotated[float, Ge(ge=0)], static_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], static_completion: Annotated[float, Ge(ge=0), Le(le=1)], recourse_cost: Annotated[float, Ge(ge=0)], recourse_hours: Annotated[float, Ge(ge=0)], recourse_budget_exceeded: Annotated[float, Ge(ge=0)], recourse_capacity_shortfall: Annotated[float, Ge(ge=0)], recourse_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], recourse_completion: Annotated[float, Ge(ge=0), Le(le=1)], deferred_actions: Annotated[int, Ge(ge=0)], deferred_hours: Annotated[float, Ge(ge=0)], risk_loss: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne annual static-versus-recourse result.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.strategic.two_stage.TwoStageError[source]
Bases:
ValueErrorRaised when two-stage inputs are inconsistent.
- class brushline.strategic.two_stage.TwoStageResult(*, schema_version: Literal['brushline.two-stage.v1'] = 'brushline.two-stage.v1', instance_id: str, year: int, episodes: Annotated[int, Ge(ge=1)], seed: int, first_stage_actions: Annotated[int, Ge(ge=0)], budget: Annotated[float, Ge(ge=0)], capacity_hours: Annotated[float, Ge(ge=0)], static_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], static_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], recourse_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], recourse_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], static_cost_band: RecourseBand, recourse_cost_band: RecourseBand, static_hours_band: RecourseBand, recourse_hours_band: RecourseBand, static_risk_band: RecourseBand, recourse_risk_band: RecourseBand, static_completion_band: RecourseBand, recourse_completion_band: RecourseBand, mean_deferred_actions: float, mean_deferred_hours: float, mean_risk_loss: float, outcomes: list[RecourseOutcome], created_utc: datetime)[source]
Bases:
BaseModelTwo-stage recourse evaluation summary.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.strategic.two_stage.evaluate_two_stage(*, instance_id: str, plan: StatefulPlan, segments: list[StatefulSegment], budget: float, capacity_hours: float, episodes: int = 100, seed: int = 23, cost_sigma: float = 0.18, hours_sigma: float = 0.15, capacity_sigma: float = 0.15, created_utc: datetime | None = None) TwoStageResult[source]
Evaluate static execution versus first-year deferral recourse.
- Parameters:
instance_id (str) – Instance id.
plan (StatefulPlan) – Fixed first-stage plan.
segments (list of StatefulSegment) – Segments with lengths and risk state.
budget (float) – Annual budget.
capacity_hours (float) – Annual crew-hour capacity.
episodes (int, optional) – Number of factor scenarios.
seed (int, optional) – Deterministic sampler seed.
cost_sigma (float, optional) – Lognormal sigmas.
hours_sigma (float, optional) – Lognormal sigmas.
capacity_sigma (float, optional) – Lognormal sigmas.
created_utc (datetime, optional) – Creation time.
- Returns:
TwoStageResult – Static and recourse bands and violation probabilities.
- Raises:
TwoStageError – If inputs are inconsistent.
- brushline.strategic.two_stage.evaluate_two_stage_multi(*, instance_id: str, plan: StatefulPlan, segments: list[StatefulSegment], periods: list[StatefulPeriod], episodes: int = 100, seed: int = 23, cost_sigma: float = 0.18, hours_sigma: float = 0.15, capacity_sigma: float = 0.15, created_utc: datetime | None = None) MultiRecourseResult[source]
Evaluate annual operational recourse across a multi-year fixed plan.