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:
ValueErrorRaised 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:
BaseModelA 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:
BaseModelOne 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:
report (StrategicReport) – Report.
path (str or Path) – Destination.
- Returns:
Path – Written path.