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:
BaseModelMonitoring 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:
BaseModelOne 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:
ValueErrorRaised 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:
BaseModelOne 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:
BaseModelA 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:
BaseModelOne 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:
BaseModelOne 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:
spans (list of MonitoringSpan) – Spans.
options (list of MonitoringOption) – Options.
- Returns:
ContractValidation – Errors and counts.