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: BaseModel

One 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: BaseModel

Multi-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: BaseModel

P10/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: BaseModel

Observed 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: BaseModel

Static 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: BaseModel

One 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: ValueError

Raised 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: BaseModel

Two-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.