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:
BaseModelThe 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:
BaseModelThe 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:
BaseModelThe 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, orretired.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:
ValueErrorRaised 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:
BaseModelTraining 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:
BaseModelA 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:
BaseModelOne 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:
BaseModelHow 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:
card (LowVegetationModelCard) – Model card.
request (ModelCardRequest) – Prediction context.
- 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:
card (LowVegetationModelCard) – Model card.
request (ModelCardRequest) – Prediction context.
- 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.