brushline.strategic.monitoring

The monitoring span/option/policy models and the value-of-information selection.

Strategic monitoring policy with an approximate value of information.

Monitoring is selected per span from explicit frequency, route, sensor, sampling-intensity, cost, and uncertainty/risk-reduction options. The value-of-information proxy is declared, not a structural sensor simulation.

class brushline.strategic.monitoring.MonitoringConfig(*, horizon_years: Annotated[int, Ge(ge=1), Le(le=50)] = 10, start_year: Annotated[int, Ge(ge=1900), Le(le=2200)] = 2026, budget: Annotated[float, Ge(ge=0)] = 0, value_per_unit: Annotated[float, Ge(ge=0)] = 1000.0, cost_weight: Annotated[float, Ge(ge=0)] = 1.0, min_net_value: Annotated[float, Ge(ge=0)] = 0.0)[source]

Bases: BaseModel

Monitoring policy settings.

Parameters:
  • horizon_years (int) – Policy horizon.

  • start_year (int) – First year.

  • budget (float) – Total monitoring budget.

  • value_per_unit (float) – Value per unit of uncertainty/risk reduction.

  • cost_weight (float) – Cost penalty in the value proxy.

  • min_net_value (float) – Minimum net value for a selection.

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

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

class brushline.strategic.monitoring.MonitoringDecision(*, span_id: str, option_id: str, sensor: str, route: str, interval_years: Annotated[int, Ge(ge=1)], sampling_intensity: Annotated[float, Ge(ge=0), Le(le=1)], start_year: int, end_year: int, event_years: Annotated[list[int], MinLen(min_length=1)], total_cost: Annotated[float, Ge(ge=0)], value_of_information: float, net_value: float, expected_uncertainty_reduction: Annotated[float, Ge(ge=0), Le(le=1)], expected_risk_reduction: Annotated[float, Ge(ge=0), Le(le=1)])[source]

Bases: BaseModel

One selected monitoring policy.

Parameters:
  • span_id (str) – Span id.

  • option_id (str) – Option id.

  • sensor (str) – Sensor.

  • route (str) – Route.

  • interval_years (int) – Interval.

  • sampling_intensity (float) – Sampling intensity.

  • start_year (int) – First year.

  • end_year (int) – Last year.

  • event_years (list of int) – Scheduled event years.

  • total_cost (float) – Total cost.

  • value_of_information (float) – Gross value proxy.

  • net_value (float) – Gross value minus cost penalty.

  • expected_uncertainty_reduction (float) – Absolute reduction.

  • expected_risk_reduction (float) – Absolute reduction.

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

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

exception brushline.strategic.monitoring.MonitoringError[source]

Bases: ValueError

Raised when monitoring inputs are inconsistent.

class brushline.strategic.monitoring.MonitoringOption(*, option_id: Annotated[str, MinLen(min_length=1)], span_id: Annotated[str, MinLen(min_length=1)], sensor: Literal['lidar', 'uav_lidar', 'imagery', 'field', 'inspection', 'other'], route: Annotated[str, MinLen(min_length=1)], interval_years: Annotated[int, Ge(ge=1), Le(le=30)], sampling_intensity: Annotated[float, Ge(ge=0), Le(le=1)], cost_per_event: Annotated[float, Ge(ge=0)], uncertainty_reduction: Annotated[float, Ge(ge=0), Le(le=1)], risk_reduction: Annotated[float, Ge(ge=0), Le(le=1)])[source]

Bases: BaseModel

One monitoring option for one span.

Parameters:
  • option_id (str) – Option id.

  • span_id (str) – Span id.

  • sensor (str) – Sensor.

  • route (str) – Route pattern or label.

  • interval_years (int) – Nominal monitoring interval.

  • sampling_intensity (float) – Sampling intensity from 0 to 1.

  • cost_per_event (float) – Cost per monitoring event.

  • uncertainty_reduction (float) – Relative uncertainty reduction from 0 to 1.

  • risk_reduction (float) – Relative service-risk reduction from 0 to 1.

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

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

class brushline.strategic.monitoring.MonitoringPolicy(*, schema_version: ~typing.Literal['brushline.strategic-monitoring.v1'] = 'brushline.strategic-monitoring.v1', policy_id: str, instance_id: str, config: ~brushline.strategic.monitoring.MonitoringConfig, decisions: list[~brushline.strategic.monitoring.MonitoringDecision], total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], expected_uncertainty_reduction: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], expected_risk_reduction: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], total_net_value: float, feasible: bool, violations: list[~brushline.strategic.monitoring.MonitoringViolation] = <factory>, caveats: list[str] = <factory>, created_utc: ~datetime.datetime)[source]

Bases: BaseModel

A strategic monitoring policy.

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

  • policy_id (str) – Policy id.

  • instance_id (str) – Instance id.

  • config (MonitoringConfig) – Settings.

  • decisions (list of MonitoringDecision) – Selected monitoring decisions.

  • total_cost (float) – Total cost.

  • budget (float) – Budget.

  • expected_uncertainty_reduction (float) – Aggregate reduction.

  • expected_risk_reduction (float) – Aggregate reduction.

  • total_net_value (float) – Sum of net values.

  • feasible (bool) – Constraints satisfied.

  • violations (list of MonitoringViolation) – Violations.

  • caveats (list of str) – Approximation 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.monitoring.MonitoringSpan(*, span_id: Annotated[str, MinLen(min_length=1)], segment_ids: Annotated[list[str], MinLen(min_length=1)], baseline_uncertainty: Annotated[float, Ge(ge=0), Le(le=1)], service_risk: Annotated[float, Ge(ge=0), Le(le=1)], route_m: Annotated[float, Gt(gt=0)])[source]

Bases: BaseModel

One monitoring span.

Parameters:
  • span_id (str) – Span id.

  • segment_ids (list of str) – Segments in the span.

  • baseline_uncertainty (float) – Current uncertainty from 0 to 1.

  • service_risk (float) – Current service risk from 0 to 1.

  • route_m (float) – Route length in metres.

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

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

class brushline.strategic.monitoring.MonitoringViolation(*, code: str, message: str, span_id: str | None = None)[source]

Bases: BaseModel

One named monitoring violation.

Parameters:
  • code (str) – Code.

  • message (str) – Explanation.

  • span_id (str or None) – Span.

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

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

brushline.strategic.monitoring.build_monitoring_policy(*, policy_id: str, instance_id: str, spans: list[MonitoringSpan], options: list[MonitoringOption], config: MonitoringConfig | None = None, created_utc: datetime | None = None) → MonitoringPolicy[source]

Select monitoring by net value of information under a total budget.

Parameters:
  • policy_id (str) – Policy id.

  • instance_id (str) – Instance id.

  • spans (list of MonitoringSpan) – Spans.

  • options (list of MonitoringOption) – Options.

  • config (MonitoringConfig, optional) – Settings.

  • created_utc (datetime, optional) – Creation time.

Returns:

MonitoringPolicy – Policy and value-of-information evidence.

brushline.strategic.monitoring.validate_monitoring_inputs(spans: list[MonitoringSpan], options: list[MonitoringOption]) → ContractValidation[source]

Validate span and option references and duplicate ids.

Parameters:
Returns:

ContractValidation – Errors and counts.