brushline.strategic.portfolio

The strategic option, segment, period, constraint, period-summary, and portfolio models plus the deterministic builder.

Strategic network portfolio selection.

The portfolio chooses at most one strategic option for each segment and period under period budgets, method capacities, a service-level target, a risk target, and a spatial-continuity preference. It uses a deterministic service-repair pass followed by budget-preserving improvement and local swaps.

class brushline.strategic.portfolio.PeriodSummary(*, period_id: str, cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], capacity_used: dict[str, float] = <factory>, service_attainment: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], uncertainty: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], selected_count: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)])[source]

Bases: BaseModel

One period’s portfolio totals.

Parameters:
  • period_id (str) – Period.

  • cost (float) – Selected cost.

  • budget (float) – Period budget.

  • capacity_used (dict of str to float) – Capacity used by method.

  • service_attainment (float) – Length-weighted service.

  • risk (float) – Length-weighted risk.

  • uncertainty (float) – Length-weighted uncertainty.

  • selected_count (int) – Selected options.

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

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

class brushline.strategic.portfolio.PortfolioConfig(*, service_target: Annotated[float, Ge(ge=0), Le(le=1)] = 0.5, risk_target: Annotated[float, Ge(ge=0), Le(le=1)] = 1.0, service_weight: Annotated[float, Ge(ge=0)] = 1.0, risk_weight: Annotated[float, Ge(ge=0)] = 1.0, uncertainty_weight: Annotated[float, Ge(ge=0)] = 0.5, cost_weight: Annotated[float, Ge(ge=0)] = 0.001, continuity_weight: Annotated[float, Ge(ge=0)] = 0.1, max_steps: Annotated[int, Ge(ge=1), Le(le=10000)] = 100, seed: int = 1)[source]

Bases: BaseModel

Portfolio weights and targets.

Parameters:
  • service_target (float) – Hard aggregate service target.

  • risk_target (float) – Soft aggregate risk target.

  • service_weight (float) – Objective weight.

  • risk_weight (float) – Objective weight.

  • uncertainty_weight (float) – Objective weight.

  • cost_weight (float) – Objective weight per cost unit.

  • continuity_weight (float) – Penalty for missing adjacent treatment pairs.

  • max_steps (int) – Maximum improvement steps.

  • seed (int) – Deterministic scenario seed.

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

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

exception brushline.strategic.portfolio.PortfolioError[source]

Bases: ValueError

Raised when portfolio data or constraints are inconsistent.

class brushline.strategic.portfolio.PortfolioOption(*, option_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], period_id: Annotated[str, MinLen(min_length=1)], action_id: Annotated[str, MinLen(min_length=1)], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'] | None = None, cost: Annotated[float, Ge(ge=0)], capacity_units: Annotated[float, Ge(ge=0)] = 0, service_attainment: Annotated[float, Ge(ge=0), Le(le=1)], risk: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]

Bases: BaseModel

One selectable segment-period option.

Parameters:
  • option_id (str) – Stable option id.

  • segment_id (str) – Segment id.

  • period_id (str) – Period id.

  • action_id (str) – Strategic action id.

  • method (str or None) – Treatment method.

  • cost (float) – Cost.

  • capacity_units (float) – Capacity consumption.

  • service_attainment (float) – Service outcome.

  • risk (float) – Risk outcome.

  • uncertainty (float) – Uncertainty outcome.

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

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

class brushline.strategic.portfolio.PortfolioPeriod(*, period_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], start_year: ~typing.Annotated[int, ~annotated_types.Ge(ge=1900), ~annotated_types.Le(le=2200)], budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], capacity_by_method: dict[str, float] = <factory>)[source]

Bases: BaseModel

One strategic period.

Parameters:
  • period_id (str) – Period id.

  • start_year (int) – Year.

  • budget (float) – Treatment budget.

  • capacity_by_method (dict of str to float) – Capacity units by method.

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

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

class brushline.strategic.portfolio.PortfolioSegment(*, segment_id: Annotated[str, MinLen(min_length=1)], span_id: Annotated[str, MinLen(min_length=1)], sequence: Annotated[int, Ge(ge=0)], length_m: Annotated[float, Gt(gt=0)], base_service: Annotated[float, Ge(ge=0), Le(le=1)], base_risk: Annotated[float, Ge(ge=0), Le(le=1)], base_uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]

Bases: BaseModel

One segment in a strategic portfolio.

Parameters:
  • segment_id (str) – Segment id.

  • span_id (str) – Span id.

  • sequence (int) – Position within the span.

  • length_m (float) – Segment length.

  • base_service (float) – No-treatment service attainment.

  • base_risk (float) – No-treatment risk.

  • base_uncertainty (float) – No-treatment uncertainty.

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

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

class brushline.strategic.portfolio.PortfolioSelection(*, option_id: str, segment_id: str, period_id: str, action_id: str, cost: Annotated[float, Ge(ge=0)], service_attainment: Annotated[float, Ge(ge=0), Le(le=1)], risk: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]

Bases: BaseModel

One selected option.

Parameters:
  • option_id (str) – Option id.

  • segment_id (str) – Segment id.

  • period_id (str) – Period id.

  • action_id (str) – Action id.

  • cost (float) – Cost.

  • service_attainment (float) – Service outcome.

  • risk (float) – Risk outcome.

  • uncertainty (float) – Uncertainty outcome.

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

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

class brushline.strategic.portfolio.PortfolioViolation(*, code: Annotated[str, MinLen(min_length=1)], message: Annotated[str, MinLen(min_length=1)], period_id: str | None = None, segment_id: str | None = None)[source]

Bases: BaseModel

One named portfolio violation.

Parameters:
  • code (str) – Violation code.

  • message (str) – Human explanation.

  • period_id (str or None) – Period.

  • segment_id (str or None) – Segment.

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

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

class brushline.strategic.portfolio.StrategicPortfolio(*, schema_version: ~typing.Literal['brushline.strategic-portfolio.v1'] = 'brushline.strategic-portfolio.v1', portfolio_id: str, instance_id: str, config: ~brushline.strategic.portfolio.PortfolioConfig, selections: list[~brushline.strategic.portfolio.PortfolioSelection], period_summary: list[~brushline.strategic.portfolio.PeriodSummary], total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], service_attainment: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], uncertainty: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], baseline_service: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], baseline_risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], baseline_uncertainty: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], continuity_score: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], objective: float, feasible: bool, violations: list[~brushline.strategic.portfolio.PortfolioViolation] = <factory>, soft_violations: list[~brushline.strategic.portfolio.PortfolioViolation] = <factory>, created_utc: ~datetime.datetime)[source]

Bases: BaseModel

A solved strategic portfolio.

Parameters:
  • schema_version ({"brushline.strategic-portfolio.v1"}) – Schema version.

  • portfolio_id (str) – Portfolio id.

  • instance_id (str) – Instance id.

  • config (PortfolioConfig) – Weights and targets.

  • selections (list of PortfolioSelection) – Selected options.

  • period_summary (list of PeriodSummary) – Period totals.

  • total_cost (float) – Total cost.

  • service_attainment (float) – Aggregate service.

  • risk (float) – Aggregate risk.

  • uncertainty (float) – Aggregate uncertainty.

  • baseline_service (float) – No-treatment service.

  • baseline_risk (float) – No-treatment risk.

  • baseline_uncertainty (float) – No-treatment uncertainty.

  • continuity_score (float) – Share of adjacent pairs with both treatments selected.

  • objective (float) – Weighted portfolio objective.

  • feasible (bool) – Hard constraints satisfied.

  • violations (list of PortfolioViolation) – Hard violations.

  • soft_violations (list of PortfolioViolation) – Soft violations.

  • created_utc (datetime) – Timezone-aware creation time.

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

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

brushline.strategic.portfolio.build_strategic_portfolio(*, portfolio_id: str, instance_id: str, segments: list[PortfolioSegment], periods: list[PortfolioPeriod], options: list[PortfolioOption], config: PortfolioConfig | None = None, created_utc: datetime | None = None) → StrategicPortfolio[source]

Build and improve a strategic portfolio.

Parameters:
  • portfolio_id (str) – Portfolio id.

  • instance_id (str) – Instance id.

  • segments (list of PortfolioSegment) – Segments.

  • periods (list of PortfolioPeriod) – Periods.

  • options (list of PortfolioOption) – Selectable options.

  • config (PortfolioConfig, optional) – Targets and weights.

  • created_utc (datetime, optional) – Creation time.

Returns:

StrategicPortfolio – Selected portfolio and report.

Raises:

PortfolioError – When inputs are invalid.

brushline.strategic.portfolio.validate_portfolio_inputs(segments: list[PortfolioSegment], periods: list[PortfolioPeriod], options: list[PortfolioOption]) → ContractValidation[source]

Validate segment/period references, option uniqueness, and non-negativity.

Parameters:
Returns:

ContractValidation – Errors and counts.