brushline.state_init

The segment-evidence models, state decision audit, prototype CHM rules, initial state contract, and state-initialization validator.

Initial vegetation state from LiDAR, field, inventory, and site evidence.

The initializer links the P3.1 to P3.3 products to the brushline.state.v1 contract. It uses field evidence first, a conservative CHM rule second, and an explicit unknown/partial state when evidence is missing or out of domain. It does not run the P4 growth or treatment model, fit a site-index model, or claim that a CHM resolves shrub from young-tree species.

class brushline.state_init.FieldObservation(*, observation_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], observed_date: date, state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'], functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], height_m: Annotated[float, Ge(ge=0)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], density_per_ha: Annotated[float | None, Ge(ge=0)] = None, age_years: Annotated[int | None, Ge(ge=0)] = None, coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)], height_error_m: Annotated[float, Ge(ge=0)] = 0.0, cover_error_pct: Annotated[float, Ge(ge=0)] = 0.0, confidence: Annotated[float, Ge(ge=0), Le(le=1)] = 0.8, source: Annotated[str, MinLen(min_length=1)], source_version: Annotated[str, MinLen(min_length=1)], model_card_id: str | None = None)[source]

Bases: BaseModel

Field evidence for one segment.

Parameters:
  • observation_id (str) – Stable observation id.

  • segment_id (str) – Segment id.

  • observed_date (datetime.date) – Observation date.

  • state_class (str) – Field state class.

  • functional_group (str) – Field functional group.

  • height_m (float) – Field height.

  • cover_pct (float) – Field cover.

  • density_per_ha (float or None) – Field density.

  • age_years (int or None) – Age since disturbance.

  • coverage_pct (float) – Field coverage of the segment.

  • height_error_m (float) – Height error.

  • cover_error_pct (float) – Cover error.

  • confidence (float) – Field confidence.

  • source (str) – Field source.

  • source_version (str) – Source version.

  • model_card_id (str or None) – Optional field model card.

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

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

class brushline.state_init.InventoryEvidence(*, segment_id: Annotated[str, MinLen(min_length=1)], height_m: Annotated[float, Ge(ge=0)], cover_pct: Annotated[float, Ge(ge=0), Le(le=100)], vintage: Annotated[str, MinLen(min_length=1)], source: Annotated[str, MinLen(min_length=1)], source_version: Annotated[str, MinLen(min_length=1)], model_card_id: str | None = None)[source]

Bases: BaseModel

VRI or inventory context for one segment.

Parameters:
  • segment_id (str) – Segment id.

  • height_m (float) – Inventory height.

  • cover_pct (float) – Inventory cover.

  • vintage (str) – Inventory vintage.

  • source (str) – Inventory source.

  • source_version (str) – Source version.

  • model_card_id (str or None) – Optional model card.

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

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

class brushline.state_init.SegmentEvidence(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], canopy: ~brushline.integrations.canopy.CanopySupport | None = None, canopy_source: ~brushline.integrations.lidar.LidarProductProvenance | None = None, terrain: ~brushline.integrations.terrain.TerrainSupport | None = None, field_observations: list[~brushline.state_init.FieldObservation] = <factory>, inventory: ~brushline.state_init.InventoryEvidence | None = None, site_index: ~brushline.state_init.SiteIndexEvidence | None = None, climate_zone: str = '', disturbance: str = '', treatment_history: list[str] = <factory>, functional_group_hint: str | None = None)[source]

Bases: BaseModel

All evidence for one segment’s initial state.

Parameters:
  • segment_id (str) – Segment id.

  • canopy (CanopySupport or None) – P3.3 canopy support.

  • terrain (TerrainSupport or None) – P3.2 terrain support.

  • field_observations (list of FieldObservation) – Field evidence.

  • inventory (InventoryEvidence or None) – Inventory context.

  • site_index (SiteIndexEvidence or None) – Site-index context.

  • climate_zone (str) – Climate or BEC context.

  • disturbance (str) – Disturbance context.

  • treatment_history (list of str) – Treatment action ids.

  • functional_group_hint (str or None) – Optional species/functional-group hint.

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

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

class brushline.state_init.SiteIndexEvidence(*, segment_id: Annotated[str, MinLen(min_length=1)], site_index_m: Annotated[float, Ge(ge=0)], species: Annotated[str, MinLen(min_length=1)], source: Annotated[str, MinLen(min_length=1)], source_version: Annotated[str, MinLen(min_length=1)], model_card_id: str | None = None)[source]

Bases: BaseModel

Site-index context for one segment.

Parameters:
  • segment_id (str) – Segment id.

  • site_index_m (float) – Reconciled site index.

  • species (str) – Species label.

  • source (str) – Source.

  • source_version (str) – Source version.

  • model_card_id (str or None) – Optional model card.

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

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

class brushline.state_init.StateDecision(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], state_class: ~typing.Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'], functional_group: ~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], confidence: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], source: str, coverage_state: str, 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)], class_probabilities: dict[str, float] = <factory>, model_card_id: str | None = None, observation_id: str | None = None, reason: str = '', inventory_vintage: str = '', site_index_m: float | None = None, climate_zone: str = '', disturbance: str = '')[source]

Bases: BaseModel

The audit record for one segment’s initial state.

Parameters:
  • segment_id (str) – Segment id.

  • state_class (str) – Selected state class.

  • functional_group (str) – Selected functional group.

  • confidence (float) – Confidence from 0 to 1.

  • source (str) – Evidence source.

  • coverage_state (str) – Canopy or field coverage state.

  • height_m (float) – State height.

  • cover_pct (float) – State cover.

  • class_probabilities (dict of str to float) – Class probabilities.

  • model_card_id (str or None) – Model card.

  • observation_id (str or None) – Observation id.

  • reason (str) – Decision reason.

  • inventory_vintage (str) – Inventory vintage, when present.

  • site_index_m (float or None) – Site index, when present.

  • climate_zone (str) – Climate context.

  • disturbance (str) – Disturbance context.

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

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

class brushline.state_init.StateInitializationConfig(*, state_year: Annotated[int, Ge(ge=1900), Le(le=2200)] = 2026, grass_max_height_m: Annotated[float, Gt(gt=0)] = 0.5, shrub_max_height_m: Annotated[float, Gt(gt=0)] = 4.0, young_tree_max_height_m: Annotated[float, Gt(gt=0)] = 10.0, cover_min_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 20.0, mature_edge_height_m: Annotated[float, Gt(gt=0)] = 15.0, mature_edge_cover_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 20.0, field_min_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)] = 50.0, field_min_confidence: Annotated[float, Ge(ge=0), Le(le=1)] = 0.5)[source]

Bases: BaseModel

Thresholds and evidence rules for the initial state.

Parameters:
  • state_year (int) – State year.

  • grass_max_height_m (float, optional) – Maximum height for a grass/herb candidate. Defaults to 0.5.

  • shrub_max_height_m (float, optional) – Maximum height for a shrub candidate. Defaults to 4.

  • young_tree_max_height_m (float, optional) – Maximum height for a young-tree candidate. Defaults to 10.

  • cover_min_pct (float, optional) – Minimum cover for a woody class. Defaults to 20.

  • mature_edge_height_m (float, optional) – Maximum-height threshold for a mature edge. Defaults to 15.

  • mature_edge_cover_pct (float, optional) – Cover threshold for a mature edge. Defaults to 20.

  • field_min_coverage_pct (float, optional) – Minimum field coverage. Defaults to 50.

  • field_min_confidence (float, optional) – Minimum field confidence. Defaults to 0.5.

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

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

exception brushline.state_init.StateInitializationError[source]

Bases: ValueError

Raised when the evidence cannot produce a valid initial state.

class brushline.state_init.StateInitializationReport(*, schema_version: ~typing.Literal['brushline.state-initialization.v1'] = 'brushline.state-initialization.v1', created_utc: ~datetime.datetime, config: ~brushline.state_init.StateInitializationConfig, contract: ~brushline.model.state.StateContract, decisions: ~typing.Annotated[list[~brushline.state_init.StateDecision], ~annotated_types.MinLen(min_length=1)], open_questions: list[str] = <factory>)[source]

Bases: BaseModel

The result of an initial-state run.

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

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

  • config (StateInitializationConfig) – Thresholds and evidence rules.

  • contract (StateContract) – The brushline.state.v1 output.

  • decisions (list of StateDecision) – Per-segment audit records.

  • open_questions (list of str) – Issues the reviewer must see.

model_config = {'extra': 'forbid'}

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

brushline.state_init.initialize_state(segments: list[SegmentEvidence], config: StateInitializationConfig | None = None, *, created_utc: datetime | None = None) → StateInitializationReport[source]

Initialize one state per segment from field, CHM, and context evidence.

Parameters:
  • segments (list of SegmentEvidence) – Evidence for each segment.

  • config (StateInitializationConfig, optional) – Thresholds and evidence rules.

  • created_utc (datetime, optional) – Report time. Defaults to the current UTC time.

Returns:

StateInitializationReport – The validated state contract and audit decisions.

Raises:

StateInitializationError – When the segment list is empty or the evidence cannot produce a valid state.

brushline.state_init.validate_state_initialization(report: StateInitializationReport) → ContractValidation[source]

Validate the state contract and its audit records.

Parameters:

report (StateInitializationReport) – Report to validate.

Returns:

ContractValidation – Errors, warnings, and counts.