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:
BaseModelField 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:
BaseModelVRI 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:
BaseModelAll 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:
BaseModelSite-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:
BaseModelThe 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:
BaseModelThresholds 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:
ValueErrorRaised 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:
BaseModelThe 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.