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:
BaseModelOne 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:
BaseModelA 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:
BaseModelSelf-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:
ValueErrorRaised 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_optimizationandaccessare also required.strategic (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare also required.tactical (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare also required.resources (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare also required.operations (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare also required.shifts (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare also required.bid (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare also required.uncertainty (mapping) – Loaded model artifacts.
scenario_optimizationandaccessare 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.