brushline.vegetation.model_card

The low-vegetation model-card, applicability-domain, uncertainty, evidence, metrics, candidate benchmark, and domain-check contract.

Low-vegetation model card and applicability-domain contract.

The model card is the inspectable boundary of the P4 model: its predictors, training and validation evidence, error and interval coverage, applicability domain, licence, citation, caveats, and decision boundary. The domain check rejects an out-of-domain prediction instead of allowing a silent extrapolation.

class brushline.vegetation.model_card.ApplicabilityDomain(*, functional_groups: Annotated[list[Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb']], MinLen(min_length=1)], treatment_methods: Annotated[list[Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other']], MinLen(min_length=1)], site_index_min_m: Annotated[float, Ge(ge=0)], site_index_max_m: Annotated[float, Gt(gt=0)], climate_factor_min: Annotated[float, Gt(gt=0)], climate_factor_max: Annotated[float, Gt(gt=0)], max_lag_years: Annotated[int, Ge(ge=0)], min_coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)])[source]

Bases: BaseModel

The predictor and context domain.

Parameters:
  • functional_groups (list of str) – Supported functional groups.

  • treatment_methods (list of str) – Supported treatment methods.

  • site_index_min_m (float) – Minimum site index.

  • site_index_max_m (float) – Maximum site index.

  • climate_factor_min (float) – Minimum climate factor.

  • climate_factor_max (float) – Maximum climate factor.

  • max_lag_years (int) – Maximum prediction lag.

  • min_coverage_pct (float) – Minimum observation coverage.

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

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

class brushline.vegetation.model_card.DomainCheck(*, in_domain: bool, reasons: list[str] = <factory>, model_id: str, version: str)[source]

Bases: BaseModel

The result of a model-card domain check.

Parameters:
  • in_domain (bool) – Whether the request is inside the domain.

  • reasons (list of str) – Named domain failures.

  • model_id (str) – Model id.

  • version (str) – Model version.

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

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

class brushline.vegetation.model_card.LowVegetationModelCard(*, schema_version: ~typing.Literal['brushline.low-vegetation-model-card.v1'] = 'brushline.low-vegetation-model-card.v1', model_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], name: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], version: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], status: str, created_utc: ~datetime.datetime, licence: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], citation: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], description: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], predictors: ~typing.Annotated[list[~brushline.vegetation.model_card.PredictorSpec], ~annotated_types.MinLen(min_length=1)], functional_groups: ~typing.Annotated[list[~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb']], ~annotated_types.MinLen(min_length=1)], domain: ~brushline.vegetation.model_card.ApplicabilityDomain, training: ~brushline.vegetation.model_card.ModelCardEvidence, validation: ~brushline.vegetation.model_card.ModelCardEvidence, metrics: ~typing.Annotated[list[~brushline.vegetation.validation.MetricSummary], ~annotated_types.MinLen(min_length=1)], candidates: list[~brushline.vegetation.validation.CandidateSummary] = <factory>, uncertainty: ~brushline.vegetation.model_card.UncertaintyContract, caveats: ~typing.Annotated[list[str], ~annotated_types.MinLen(min_length=1)], decision_boundary: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)])[source]

Bases: BaseModel

The versioned low-vegetation model card.

Parameters:
  • schema_version ({"brushline.low-vegetation-model-card.v1"}) – Card schema version.

  • model_id (str) – Model id.

  • name (str) – Human name.

  • version (str) – Model version.

  • status (str) – prototype, candidate, approved, or retired.

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

  • licence (str) – Model licence.

  • citation (str) – Citation.

  • description (str) – Short description.

  • predictors (list of PredictorSpec) – Predictor specs.

  • functional_groups (list of str) – Supported groups.

  • domain (ApplicabilityDomain) – Applicability domain.

  • training (ModelCardEvidence) – Training evidence.

  • validation (ModelCardEvidence) – Validation evidence.

  • metrics (list of MetricSummary) – Validation metrics.

  • candidates (list of CandidateSummary) – Candidate benchmark.

  • uncertainty (UncertaintyContract) – Uncertainty contract.

  • caveats (list of str) – Caveats.

  • decision_boundary (str) – Decision-support boundary.

model_config = {'extra': 'forbid'}

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

exception brushline.vegetation.model_card.ModelCardDomainError[source]

Bases: ValueError

Raised when a prediction is outside the model card domain.

class brushline.vegetation.model_card.ModelCardEvidence(*, dataset_id: Annotated[str, MinLen(min_length=1)], source: Annotated[str, MinLen(min_length=1)], source_version: Annotated[str, MinLen(min_length=1)], licence: Annotated[str, MinLen(min_length=1)], n_records: Annotated[int, Ge(ge=1)], spatial_blocks: Annotated[list[str], MinLen(min_length=1)], period: Annotated[str, MinLen(min_length=1)], provenance: Annotated[str, MinLen(min_length=1)])[source]

Bases: BaseModel

Training or validation evidence.

Parameters:
  • dataset_id (str) – Dataset id.

  • source (str) – Source.

  • source_version (str) – Source version.

  • licence (str) – Data licence.

  • n_records (int) – Record count.

  • spatial_blocks (list of str) – Spatial blocks.

  • period (str) – Observation period.

  • provenance (str) – Provenance reference.

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

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

class brushline.vegetation.model_card.ModelCardRequest(*, functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], treatment_method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], site_index_m: Annotated[float, Ge(ge=0)], climate_factor: Annotated[float, Gt(gt=0)], lag_years: Annotated[int, Ge(ge=0)], coverage_pct: Annotated[float, Ge(ge=0), Le(le=100)])[source]

Bases: BaseModel

A prediction context for the domain check.

Parameters:
  • functional_group (str) – Functional group.

  • treatment_method (str) – Treatment method.

  • site_index_m (float) – Site index.

  • climate_factor (float) – Climate factor.

  • lag_years (int) – Prediction lag.

  • coverage_pct (float) – Observation coverage.

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

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

class brushline.vegetation.model_card.PredictorSpec(*, name: Annotated[str, MinLen(min_length=1)], unit: Annotated[str, MinLen(min_length=1)], minimum: float, maximum: float, required: bool = True, description: str = '')[source]

Bases: BaseModel

One predictor and its accepted range.

Parameters:
  • name (str) – Predictor name.

  • unit (str) – Unit.

  • minimum (float) – Lower accepted value.

  • maximum (float) – Upper accepted value.

  • required (bool, optional) – Whether the predictor is required. Defaults to True.

  • description (str) – Short description.

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

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

class brushline.vegetation.model_card.UncertaintyContract(*, interval_level: Annotated[float, Gt(gt=0.5), Lt(lt=1)] = 0.95, height_interval: Annotated[str, MinLen(min_length=1)], cover_interval: Annotated[str, MinLen(min_length=1)], density_interval: Annotated[str, MinLen(min_length=1)], propagation: Annotated[str, MinLen(min_length=1)], caveat: Annotated[str, MinLen(min_length=1)])[source]

Bases: BaseModel

How uncertainty is represented and propagated.

Parameters:
  • interval_level (float) – Interval coverage level.

  • height_interval (str) – Height interval semantics.

  • cover_interval (str) – Cover interval semantics.

  • density_interval (str) – Density interval semantics.

  • propagation (str) – How uncertainty enters the transition model.

  • caveat (str) – Decision-support caveat.

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

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

brushline.vegetation.model_card.check_domain(card: LowVegetationModelCard, request: ModelCardRequest) → DomainCheck[source]

Check a prediction request against the card’s applicability domain.

Parameters:
Returns:

DomainCheck – In-domain flag and named reasons.

brushline.vegetation.model_card.require_in_domain(card: LowVegetationModelCard, request: ModelCardRequest) → DomainCheck[source]

Return a passing domain check or raise.

Parameters:
Returns:

DomainCheck – The passing check.

Raises:

ModelCardDomainError – When the request is outside the domain.

brushline.vegetation.model_card.validate_model_card(card: LowVegetationModelCard) → ContractValidation[source]

Validate the model card and its evidence.

Parameters:

card (LowVegetationModelCard) – Card to validate.

Returns:

ContractValidation – Errors, warnings, and counts.