Planning brief API

Generate a self-contained planning brief from network model artifacts.

The brief is a decision record, not a replacement for the underlying plans. It packages the selected frontier point, tactical schedule, workforce scenarios, commercial check, uncertainty bands, scenario comparison, provenance, and caveats into one offline-readable document.

class brushline.strategic.planning_brief.BriefSection(*, heading: str, paragraphs: list[str] = <factory>, bullets: list[str] = <factory>, table: BriefTable | None = None)[source]

Bases: BaseModel

One section of a planning brief.

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

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

class brushline.strategic.planning_brief.BriefTable(*, columns: list[str], rows: list[list[str]], note: str | None = None)[source]

Bases: BaseModel

A rendered table in a planning brief.

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

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

class brushline.strategic.planning_brief.PlanningBrief(*, schema_version: Literal['brushline.planning-brief.v1'] = 'brushline.planning-brief.v1', instance_id: str, title: str, generated_utc: datetime, command: str, commit: str, markdown: str, html: str, filename_markdown: str, filename_html: str)[source]

Bases: BaseModel

Self-contained Markdown and HTML planning brief.

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

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

exception brushline.strategic.planning_brief.PlanningBriefError[source]

Bases: ValueError

Raised when planning-brief inputs are missing or inconsistent.

brushline.strategic.planning_brief.build_planning_brief(*, network: Mapping[str, Any], strategic: Mapping[str, Any], tactical: Mapping[str, Any], resources: Mapping[str, Any], operations: Mapping[str, Any], shifts: Mapping[str, Any], workforce: Sequence[Mapping[str, Any]], bid: Mapping[str, Any], uncertainty: Mapping[str, Any], scenario_optimization: Mapping[str, Any], access: Mapping[str, Any], rolling_policy: Mapping[str, Any] | None = None, policy_execution: Mapping[str, Any] | None = None, policy_execution_scan: Mapping[str, Any] | None = None, static_plan: Mapping[str, Any] | None = None, operational_stress: Mapping[str, Any] | None = None, operational_stress_scan: Mapping[str, Any] | None = None, operational_remedies: Mapping[str, Any] | None = None, risk_ranked_scope: Mapping[str, Any] | None = None, risk_trajectory: Mapping[str, Any] | None = None, rolling_recovery: Mapping[str, Any] | None = None, out_of_sample_recovery: Mapping[str, Any] | None = None, deferral_frontier: Mapping[str, Any] | None = None, frontier_validation: Mapping[str, Any] | None = None, robust_plan: Mapping[str, Any] | None = None, chance_plan: Mapping[str, Any] | None = None, chance_capacity_plan: Mapping[str, Any] | None = None, chance_100_plan: Mapping[str, Any] | None = None, two_stage_policy: Mapping[str, Any] | None = None, two_stage_multi: Mapping[str, Any] | None = None, rolling_recourse: Mapping[str, Any] | None = None, rolling_recourse_590: Mapping[str, Any] | None = None, weather_recourse: Mapping[str, Any] | None = None, weather_recourse_590: Mapping[str, Any] | None = None, forecast_skill: Mapping[str, Any] | None = None, window_remedy: Mapping[str, Any] | None = None, window_remedy_590: Mapping[str, Any] | None = None, capacity_remedy: Mapping[str, Any] | None = None, capacity_remedy_590: Mapping[str, Any] | None = None, generated_utc: datetime | None = None, command: str = 'python tools/build_bc_network_demo.py', commit: str = 'unknown') → PlanningBrief[source]

Build the planning brief from the network artifact set.

Parameters:
  • network (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • strategic (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • tactical (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • resources (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • operations (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • shifts (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • bid (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • uncertainty (mapping) – Loaded model artifacts. scenario_optimization and access are also required.

  • workforce (sequence of mapping) – Workforce scenario results.

  • rolling_policy (mapping, optional) – Rolling-horizon policy result. The section is omitted when absent.

  • policy_execution (mapping, optional) – First-year policy execution package. The section is omitted when absent.

  • policy_execution_scan (mapping, optional) – All-episode first-year execution scan. The section is omitted when absent.

  • static_plan (mapping, optional) – Static frontier-plan stress evaluation. The section is omitted when absent.

  • operational_stress (mapping, optional) – Weather/outage shift stress. The section is omitted when absent.

  • operational_stress_scan (mapping, optional) – All-episode weather/outage scan. The section is omitted when absent.

  • operational_remedies (mapping, optional) – Capacity and scope remedy comparison. The section is omitted when absent.

  • risk_ranked_scope (mapping, optional) – Risk-ranked scope deferral comparison. The section is omitted when absent.

  • risk_trajectory (mapping, optional) – Multi-year risk trajectory for first-year deferral. The section is omitted when absent.

  • rolling_recovery (mapping, optional) – Future re-optimization after first-year deferral. The section is omitted when absent.

  • out_of_sample_recovery (mapping, optional) – Resampled-future recovery test. The section is omitted when absent.

  • deferral_frontier (mapping, optional) – Risk-ranked deferral fraction sweep. The section is omitted when absent.

  • frontier_validation (mapping, optional) – Out-of-sample validation of frontier candidates. The section is omitted when absent.

  • robust_plan (mapping, optional) – Scenario-robust static plan evaluation. The section is omitted when absent.

  • chance_plan (mapping, optional) – Sampled budget chance-constrained plan. The section is omitted when absent.

  • chance_capacity_plan (mapping, optional) – Sampled budget-and-capacity chance plan. The section is omitted when absent.

  • chance_100_plan (mapping, optional) – 100-path sampled budget chance plan. The section is omitted when absent.

  • two_stage_policy (mapping, optional) – First-year two-stage operational recourse. The section is omitted when absent.

  • two_stage_multi (mapping, optional) – Multi-year annual operational recourse. The section is omitted when absent.

  • rolling_recourse (mapping, optional) – Rolling policy with annual recourse. The section is omitted when absent.

  • rolling_recourse_590 (mapping, optional) – 590-segment replicated rolling-recourse scale test. The section is omitted when absent.

  • weather_recourse (mapping, optional) – Calendar-naive versus calendar-aware annual recourse. The section is omitted when absent.

  • weather_recourse_590 (mapping, optional) – 590-segment weather-recourse scale test. The section is omitted when absent.

  • forecast_skill (mapping, optional) – Forecast-skill sensitivity for calendar-aware execution. The section is omitted when absent.

  • window_remedy (mapping, optional) – Fall-window capacity remedy for calendar-aware execution. The section is omitted when absent.

  • window_remedy_590 (mapping, optional) – 590-segment fall-window remedy. The section is omitted when absent.

  • capacity_remedy (mapping, optional) – Added-crew versus longer-window comparison. The section is omitted when absent.

  • capacity_remedy_590 (mapping, optional) – 590-segment capacity-remedy comparison. The section is omitted when absent.

  • generated_utc (datetime, optional) – Generation time; defaults to the current UTC time.

  • command (str, optional) – Reproduction command.

  • commit (str, optional) – Repository commit identifier.

Returns:

PlanningBrief – Markdown and HTML renderings with filenames.

Raises:

PlanningBriefError – If required artifacts or the selected frontier point are missing.

brushline.strategic.planning_brief.render_html(*, title: str, instance_id: str, generated_utc: datetime, command: str, commit: str, sections: Sequence[BriefSection]) → str[source]

Render a self-contained, print-friendly HTML planning brief.

brushline.strategic.planning_brief.render_markdown(*, title: str, instance_id: str, generated_utc: datetime, command: str, commit: str, sections: Sequence[BriefSection]) → str[source]

Render a planning brief as GitHub-flavoured Markdown.