Uncertainty API
Execution uncertainty around a fixed tactical plan.
The sampler varies treatment cost, productive hours, and contractor capacity around a fixed plan. It does not re-optimize the plan per sample; this is execution sensitivity, not a full adaptive stochastic program.
- class brushline.strategic.uncertainty.SensitivityCase(*, name: str, cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)], total_cost: Annotated[float, Ge(ge=0)], total_hours: Annotated[float, Ge(ge=0)], budget_exceeded: Annotated[float, Ge(ge=0)], capacity_shortfall_hours: Annotated[float, Ge(ge=0)], contractor_shortfall_hours: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne deterministic one-at-a-time sensitivity case.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.uncertainty.UncertaintyBand(*, p10: float, p50: float, p90: float, mean: float)[source]
Bases:
BaseModelP10/P50/P90 band for one metric.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.uncertainty.UncertaintyConfig(*, samples: Annotated[int, Ge(ge=1), Le(le=10000)] = 500, seed: int = 7, cost_sigma: Annotated[float, Ge(ge=0), Le(le=1)] = 0.18, hours_sigma: Annotated[float, Ge(ge=0), Le(le=1)] = 0.15, capacity_sigma: Annotated[float, Ge(ge=0), Le(le=1)] = 0.15)[source]
Bases:
BaseModelDistribution settings for the execution sampler.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.strategic.uncertainty.UncertaintyError[source]
Bases:
ValueErrorRaised when uncertainty inputs are inconsistent.
- class brushline.strategic.uncertainty.UncertaintyResult(*, schema_version: Literal['brushline.uncertainty.v1'] = 'brushline.uncertainty.v1', instance_id: str, samples: Annotated[int, Ge(ge=1)], seed: int, annual_budget: Annotated[float, Ge(ge=0)], annual_capacity_hours: Annotated[float, Ge(ge=0)], baseline_cost: Annotated[float, Ge(ge=0)], baseline_hours: Annotated[float, Ge(ge=0)], cost_band: UncertaintyBand, hours_band: UncertaintyBand, budget_exceeded_band: UncertaintyBand, capacity_shortfall_band: UncertaintyBand, contractor_shortfall_band: UncertaintyBand, probability_budget_exceeded: Annotated[float, Ge(ge=0), Le(le=1)], probability_capacity_shortfall: Annotated[float, Ge(ge=0), Le(le=1)], probability_contractor_shortfall: Annotated[float, Ge(ge=0), Le(le=1)], sensitivity: list[SensitivityCase], samples_detail: list[UncertaintySample], created_utc: datetime)[source]
Bases:
BaseModelSampled execution bands and deterministic sensitivities.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.uncertainty.UncertaintySample(*, cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)], total_cost: Annotated[float, Ge(ge=0)], total_hours: Annotated[float, Ge(ge=0)], budget_exceeded: Annotated[float, Ge(ge=0)], capacity_shortfall_hours: Annotated[float, Ge(ge=0)], contractor_shortfall_hours: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne sampled execution outcome.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.strategic.uncertainty.evaluate_uncertainty(*, instance_id: str, actions: list[TacticalAction], periods: list[StatefulPeriod], profiles: list[ContractorProfile], config: UncertaintyConfig | None = None, created_utc: datetime | None = None) UncertaintyResult[source]
Sample cost, hours, and contractor capacity around a fixed plan.
- Parameters:
instance_id (str) – Instance id.
actions (list of TacticalAction) – Fixed tactical plan.
periods (list of StatefulPeriod) – Annual budgets and crew-hour capacities.
profiles (list of ContractorProfile) – Contractor capacities.
config (UncertaintyConfig, optional) – Sampler settings.
created_utc (datetime, optional) – Creation time.
- Returns:
UncertaintyResult – Percentile bands, shortfall probabilities, and one-at-a-time sensitivities.