brushline.strategic.reports

The yearly strategic report rows, optimized/BAU totals, writer, and loader.

Strategic report: yearly cost, budget, service, risk, uncertainty, and BAU comparison.

exception brushline.strategic.reports.ReportError[source]

Bases: ValueError

Raised when a strategic report is inconsistent.

class brushline.strategic.reports.StrategicReport(*, schema_version: ~typing.Literal['brushline.strategic-report.v1'] = 'brushline.strategic-report.v1', report_id: str, instance_id: str, rows: ~typing.Annotated[list[~brushline.strategic.reports.YearRow], ~annotated_types.MinLen(min_length=1)], optimized_total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], bau_total_cost: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, comparison: ~brushline.strategic.bau.BauComparison | None = None, caveats: list[str] = <factory>, created_utc: ~datetime.datetime)[source]

Bases: BaseModel

A deterministic strategic report.

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

  • report_id (str) – Report id.

  • instance_id (str) – Instance id.

  • rows (list of YearRow) – Optimized and optional BAU rows.

  • optimized_total_cost (float) – Optimized total cost.

  • bau_total_cost (float or None) – BAU total cost.

  • comparison (BauComparison or None) – Optimized/BAU comparison.

  • caveats (list of str) – Report caveats.

  • created_utc (datetime) – Timezone-aware time.

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

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

class brushline.strategic.reports.YearRow(*, scope: Literal['optimized', 'bau'], year: Annotated[int, Ge(ge=1900), Le(le=2200)], period_id: str, treatment_cost: Annotated[float, Ge(ge=0)], monitoring_cost: Annotated[float, Ge(ge=0)], total_cost: Annotated[float, Ge(ge=0)], budget: Annotated[float, Ge(ge=0)], budget_remaining: float, 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)], monitoring_events: Annotated[int, Ge(ge=0)])[source]

Bases: BaseModel

One scope/year report row.

Parameters:
  • scope ({"optimized", "bau"}) – Report scope.

  • year (int) – Calendar year.

  • period_id (str) – Period id.

  • treatment_cost (float) – Treatment cost.

  • monitoring_cost (float) – Allocated monitoring cost.

  • total_cost (float) – Total cost.

  • budget (float) – Period budget.

  • budget_remaining (float) – Budget remaining; negative means an overrun.

  • service_attainment (float) – Service.

  • risk (float) – Risk.

  • uncertainty (float) – Uncertainty.

  • monitoring_events (int) – Monitoring events allocated to the year.

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

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

brushline.strategic.reports.build_strategic_report(*, report_id: str, instance_id: str, portfolio: StrategicPortfolio, monitoring: MonitoringPolicy, periods: list[PortfolioPeriod], bau: BauPlan | None = None, comparison: BauComparison | None = None, created_utc: datetime | None = None) → StrategicReport[source]

Build optimized and optional BAU yearly rows.

Parameters:
  • report_id (str) – Report id.

  • instance_id (str) – Instance id.

  • portfolio (StrategicPortfolio) – Optimized portfolio.

  • monitoring (MonitoringPolicy) – Monitoring policy.

  • periods (list of PortfolioPeriod) – Period definitions for year mapping.

  • bau (BauPlan or None, optional) – BAU plan.

  • comparison (BauComparison or None, optional) – Comparison record.

  • created_utc (datetime, optional) – Creation time.

Returns:

StrategicReport – Yearly rows and totals.

Raises:

ReportError – When period or instance references are inconsistent.

brushline.strategic.reports.load_strategic_report(path: str | Path) → StrategicReport[source]

Load a strategic report.

Parameters:

path (str or Path) – Source.

Returns:

StrategicReport – Loaded report.

brushline.strategic.reports.write_strategic_report(report: StrategicReport, path: str | Path) → Path[source]

Write a strategic report as JSON.

Parameters:
Returns:

Path – Written path.