brushline.vegetation.hazards

The clearance, fall-in, fuel-connectivity, access, and reliability indicators, their formulas and config, and the hazard-report validator.

Hazard and service indicators from the vegetation state and corridor context.

The indicators are decision aids, not engineering certifications. Each component records its formula, units, inputs, and caveat. A missing input is unknown, never zero. The reliability proxy is a declared weighted combination of the available components.

class brushline.vegetation.hazards.AccessEvidence(*, slope_deg: Annotated[float, Ge(ge=0), Le(le=90)], road_status: Annotated[str, MinLen(min_length=1)], road_status_source: Annotated[str, MinLen(min_length=1)], road_score: Annotated[float, Ge(ge=0), Le(le=1)], distance_m: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

Source-preserving road and slope evidence.

Parameters:
  • slope_deg (float) – Local slope.

  • road_status (str) – Source road status, such as class_1.

  • road_status_source (str) – Source name for the status.

  • road_score (float) – Explicit source-preserving score from 0 to 1.

  • distance_m (float) – Distance to the road evidence.

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

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

class brushline.vegetation.hazards.AccessIndicator(*, status: str, slope_deg: float | None = None, slope_factor: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, road_status: str = '', road_status_source: str = '', road_score: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, distance_m: Annotated[float | None, Ge(ge=0)] = None, proxy: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, formula: str = 'proxy = clamp(1 - slope / zero_slope, 0, 1) * road_score')[source]

Bases: BaseModel

Slope and source-preserving road access proxy.

Parameters:
  • status (str) – high, moderate, low, or unknown.

  • slope_deg (float or None) – Local slope.

  • slope_factor (float or None) – Slope factor from 0 to 1.

  • road_status (str) – Source road status.

  • road_status_source (str) – Source name.

  • road_score (float or None) – Source score.

  • distance_m (float or None) – Distance to road evidence.

  • proxy (float or None) – Access proxy from 0 to 1.

  • formula (str) – Formula description.

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

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

class brushline.vegetation.hazards.ClearanceIndicator(*, status: str, height_m: float, max_height_m: float, min_clearance_m: float, asset_height_m: float | None, height_margin_m: float, clearance_gap_m: float | None, formula: str = 'height_margin = max_height - height; gap = asset_height - height - min_clearance')[source]

Bases: BaseModel

Clearance versus the service standard and optional asset.

Parameters:
  • status (str) – clear, at_risk, exceeded, or unknown.

  • height_m (float) – Vegetation height.

  • max_height_m (float) – Service-standard maximum.

  • min_clearance_m (float) – Service-standard clearance.

  • asset_height_m (float or None) – Asset height, when supplied.

  • height_margin_m (float) – Service maximum minus vegetation height.

  • clearance_gap_m (float or None) – Asset height minus vegetation height and minimum clearance.

  • formula (str) – Formula description.

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

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

class brushline.vegetation.hazards.FallInIndicator(*, status: str, edge_height_m: float | None, edge_distance_m: float | None, wind_factor: float, reach_m: float | None, risk: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, formula: str = 'reach = edge_height * wind_factor; risk = clamp(1 - distance / reach, 0, 1)')[source]

Bases: BaseModel

Mature-edge fall-in reach and risk.

Parameters:
  • status (str) – low, moderate, high, or unknown.

  • edge_height_m (float or None) – Tree height.

  • edge_distance_m (float or None) – Distance to the asset.

  • wind_factor (float) – Reach multiplier.

  • reach_m (float or None) – Fall-in reach.

  • risk (float or None) – Risk from 0 to 1.

  • formula (str) – Formula description.

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

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

class brushline.vegetation.hazards.FuelIndicator(*, status: str, connectivity: Annotated[float | None, Ge(ge=0), Le(le=1)] = None, neighbor_count: Annotated[int, Ge(ge=0)], formula: str = 'distance-weighted mean neighbour cover / 100')[source]

Bases: BaseModel

Fuel continuity from adjacent segments.

Parameters:
  • status (str) – low, moderate, high, or unknown.

  • connectivity (float or None) – Connectivity from 0 to 1.

  • neighbor_count (int) – Number of neighbours.

  • formula (str) – Formula description.

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

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

class brushline.vegetation.hazards.FuelNeighbor(*, segment_id: Annotated[str, MinLen(min_length=1)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], distance_m: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

One adjacent segment’s fuel evidence.

Parameters:
  • segment_id (str) – Neighbour segment id.

  • cover_pct (float) – Neighbour cover.

  • distance_m (float) – Distance from the segment.

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

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

class brushline.vegetation.hazards.HazardConfig(*, clearance_warning_m: Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, wind_factor: Annotated[float, ~annotated_types.Gt(gt=0)] = 1.5, fuel_distance_scale_m: Annotated[float, ~annotated_types.Gt(gt=0)] = 50.0, access_slope_zero_deg: Annotated[float, ~annotated_types.Gt(gt=0)] = 30.0, weights: dict[str, float]=<factory>)[source]

Bases: BaseModel

Thresholds, weights, and formula assumptions.

Parameters:
  • clearance_warning_m (float, optional) – Margin at or below which clearance is at risk. Defaults to 1.

  • wind_factor (float, optional) – Fall-in reach multiplier. Defaults to 1.5.

  • fuel_distance_scale_m (float, optional) – Neighbour decay distance. Defaults to 50.

  • access_slope_zero_deg (float, optional) – Slope at which the access slope factor reaches zero. Defaults to 30.

  • weights (dict of str to float, optional) – Reliability weights.

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

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

class brushline.vegetation.hazards.HazardReport(*, schema_version: Literal['brushline.hazards.v1'] = 'brushline.hazards.v1', created_utc: datetime, segment_id: str, clearance: ClearanceIndicator, fall_in: FallInIndicator, fuel: FuelIndicator, access: AccessIndicator, reliability: ReliabilityIndicator, caveats: list[str] = <factory>)[source]

Bases: BaseModel

The hazard report for one segment.

Parameters:
  • schema_version ({"brushline.hazards.v1"}) – Report schema version.

  • created_utc (datetime) – Timezone-aware creation time.

  • segment_id (str) – Segment id.

  • clearance (ClearanceIndicator) – Clearance evidence.

  • fall_in (FallInIndicator) – Fall-in evidence.

  • fuel (FuelIndicator) – Fuel continuity evidence.

  • access (AccessIndicator) – Access evidence.

  • reliability (ReliabilityIndicator) – Weighted reliability proxy.

  • caveats (list of str) – Decision-support caveats.

model_config = {'extra': 'forbid'}

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

class brushline.vegetation.hazards.HazardRequest(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], height_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], cover_pct: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)], height_sd_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, service_standard: ~brushline.model.corridor.ServiceStandard, asset_height_m: ~typing.Annotated[float | None, ~annotated_types.Gt(gt=0)] = None, edge_height_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, edge_distance_m: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0)] = None, neighbors: list[~brushline.vegetation.hazards.FuelNeighbor] = <factory>, access: ~brushline.vegetation.hazards.AccessEvidence | None = None)[source]

Bases: BaseModel

One segment’s hazard inputs.

Parameters:
  • segment_id (str) – Segment id.

  • height_m (float) – Mean vegetation height.

  • cover_pct (float) – Mean vegetation cover.

  • height_sd_m (float, optional) – Height standard deviation.

  • service_standard (ServiceStandard) – Service standard.

  • asset_height_m (float or None, optional) – Conductor or asset height above ground.

  • edge_height_m (float or None, optional) – Mature-edge tree height.

  • edge_distance_m (float or None, optional) – Distance from the mature edge to the asset.

  • neighbors (list of FuelNeighbor, optional) – Adjacent fuel evidence.

  • access (AccessEvidence or None, optional) – Road and slope evidence.

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

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

class brushline.vegetation.hazards.ReliabilityIndicator(*, status: str, score: ~typing.Annotated[float | None, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = None, weights: dict[str, float], components: dict[str, float] = <factory>, formula: str = 'weighted mean of available clearance, fall-in, fuel, and access scores')[source]

Bases: BaseModel

Weighted reliability proxy.

Parameters:
  • status (str) – high, moderate, low, or unknown.

  • score (float or None) – Score from 0 to 1.

  • weights (dict of str to float) – Weights used.

  • components (dict of str to float) – Available component scores.

  • formula (str) – Formula description.

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

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

brushline.vegetation.hazards.assess_hazards(request: HazardRequest, config: HazardConfig | None = None, *, created_utc: datetime | None = None) → HazardReport[source]

Assess the hazard and service indicators for one segment.

Parameters:
  • request (HazardRequest) – Vegetation, service standard, and context.

  • config (HazardConfig, optional) – Thresholds and weights.

  • created_utc (datetime, optional) – Report time.

Returns:

HazardReport – Component indicators and the reliability proxy.

brushline.vegetation.hazards.validate_hazard_report(report: HazardReport) → ContractValidation[source]

Validate the hazard statuses, ranges, and reliability composition.

Parameters:

report (HazardReport) – Report to validate.

Returns:

ContractValidation – Errors, warnings, and counts.