Static plan API

Stress-test static frontier plans against annual cost and capacity factors.

This is candidate evaluation, not robust optimization. It asks whether an existing frontier plan, built to a lower nominal budget, could serve as a fixed multi-year plan against a common actual budget and capacity.

class brushline.strategic.static_plan.StaticBand(*, 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.static_plan.StaticPlanCase(*, name: str, nominal_budget: Annotated[float, Ge(ge=0)], plan: StatefulPlan)[source]

Bases: BaseModel

One candidate static plan and its nominal budget.

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

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

exception brushline.strategic.static_plan.StaticPlanError[source]

Bases: ValueError

Raised when static-plan evaluation inputs are inconsistent.

class brushline.strategic.static_plan.StaticPlanEvaluation(*, schema_version: Literal['brushline.static-plan.v1'] = 'brushline.static-plan.v1', instance_id: str, episodes: Annotated[int, Ge(ge=1)], seed: int, actual_budget: Annotated[float, Ge(ge=0)], actual_capacity_hours: Annotated[float, Ge(ge=0)], budget_risk_limit: Annotated[float, Ge(ge=0), Le(le=1)], recommended: str | None, plans: list[StaticPlanSummary], created_utc: datetime)[source]

Bases: BaseModel

Static-plan stress evaluation against a common actual budget.

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

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

class brushline.strategic.static_plan.StaticPlanSummary(*, name: str, nominal_budget: float, cost_band: StaticBand, hours_band: StaticBand, risk: Annotated[float, Ge(ge=0), Le(le=0.95)], budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], mean_objective: float)[source]

Bases: BaseModel

Stress summary for one static candidate.

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

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

brushline.strategic.static_plan.evaluate_static_plans(*, instance_id: str, plans: list[StaticPlanCase], periods: list[StatefulPeriod], config: StatefulConfig | None = None, episodes: int = 20, seed: int = 7, cost_sigma: float = 0.18, hours_sigma: float = 0.15, capacity_sigma: float = 0.15, budget_risk_limit: float = 0.05, created_utc: datetime | None = None) → StaticPlanEvaluation[source]

Evaluate candidate static plans under common annual-factor episodes.

Parameters:
  • instance_id (str) – Instance id.

  • plans (list of StaticPlanCase) – Candidate plans with nominal budgets.

  • periods (list of StatefulPeriod) – Actual annual budget and capacity constraints.

  • config (StatefulConfig, optional) – Objective weights.

  • episodes (int, optional) – Number of factor episodes.

  • seed (int, optional) – Deterministic sampler seed.

  • cost_sigma (float, optional) – Lognormal sigmas.

  • hours_sigma (float, optional) – Lognormal sigmas.

  • capacity_sigma (float, optional) – Lognormal sigmas.

  • budget_risk_limit (float, optional) – Maximum budget-violation probability for the recommended candidate.

  • created_utc (datetime, optional) – Creation time.

Returns:

StaticPlanEvaluation – Candidate cost/risk bands, violation probabilities, and recommendation.

Raises:

StaticPlanError – If inputs are empty or invalid.