brushline.tactical.program

The treatment-unit, tactical-action, configuration, program, and validation models.

Multi-year tactical treatment program.

class brushline.tactical.program.TacticalAction(*, action_id: Annotated[str, MinLen(min_length=1)], unit_id: Annotated[str, MinLen(min_length=1)], year: Annotated[int, Ge(ge=1900), Le(le=2200)], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], contractor_id: Annotated[str, MinLen(min_length=1)], cost: Annotated[float, Ge(ge=0)], capacity_units: Annotated[float, Gt(gt=0)], access_window_id: str | None = None)[source]

Bases: BaseModel

One selected tactical action.

Parameters:
  • action_id (str) – Action id.

  • unit_id (str) – Unit id.

  • year (int) – Year.

  • season (str) – Season.

  • method (str) – Method.

  • contractor_id (str) – Contractor id.

  • cost (float) – Cost.

  • capacity_units (float) – Crew/machine units.

  • access_window_id (str or None, optional) – Access window reference.

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

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

class brushline.tactical.program.TacticalConfig(*, horizon_years: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=5)] = 5, start_year: Annotated[int, ~annotated_types.Ge(ge=1900), ~annotated_types.Le(le=2200)] = 2026, budget_by_year: dict[int, float]=<factory>, currency: str = 'CAD')[source]

Bases: BaseModel

Tactical program settings.

Parameters:
  • horizon_years (int) – Horizon from 1 to 5.

  • start_year (int) – First year.

  • budget_by_year (dict of int to float) – Budget by year.

  • currency (str) – Currency.

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

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

exception brushline.tactical.program.TacticalError[source]

Bases: ValueError

Raised when a tactical program is inconsistent.

class brushline.tactical.program.TacticalProgram(*, schema_version: ~typing.Literal['brushline.tactical-program.v1'] = 'brushline.tactical-program.v1', program_id: str, instance_id: str, config: ~brushline.tactical.program.TacticalConfig, units: list[~brushline.tactical.program.TreatmentUnit], actions: list[~brushline.tactical.program.TacticalAction], total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], budget_by_year: dict[int, float], cost_by_year: dict[int, float], contractor_allocation: dict[str, int], feasible: bool, violations: list[~brushline.tactical.program.TacticalViolation] = <factory>, created_utc: ~datetime.datetime)[source]

Bases: BaseModel

A multi-year tactical program.

Parameters:
  • schema_version ({"brushline.tactical-program.v1"}) – Schema version.

  • program_id (str) – Program id.

  • instance_id (str) – Instance id.

  • config (TacticalConfig) – Settings.

  • units (list of TreatmentUnit) – Units.

  • actions (list of TacticalAction) – Selected actions.

  • total_cost (float) – Total cost.

  • budget_by_year (dict of int to float) – Budget.

  • cost_by_year (dict of int to float) – Cost.

  • contractor_allocation (dict of str to int) – Action count by contractor.

  • feasible (bool) – Constraints satisfied.

  • violations (list of TacticalViolation) – Violations.

  • created_utc (datetime) – Timezone-aware time.

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

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

class brushline.tactical.program.TacticalViolation(*, code: str, message: str, action_id: str | None = None)[source]

Bases: BaseModel

One tactical violation.

Parameters:
  • code (str) – Code.

  • message (str) – Explanation.

  • action_id (str or None) – Action.

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

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

class brushline.tactical.program.TreatmentUnit(*, unit_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], span_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], segment_ids: ~typing.Annotated[list[str], ~annotated_types.MinLen(min_length=1)], area_ha: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], allowed_methods: list[~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other']] = <factory>, allowed_seasons: list[~typing.Literal['spring', 'summer', 'fall', 'winter', 'any']] = <factory>)[source]

Bases: BaseModel

A tactical treatment unit.

Parameters:
  • unit_id (str) – Unit id.

  • span_id (str) – Span id.

  • segment_ids (list of str) – Segments.

  • area_ha (float) – Area.

  • allowed_methods (list of str) – Allowed methods.

  • allowed_seasons (list of str) – Allowed seasons.

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

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

brushline.tactical.program.build_tactical_program(*, program_id: str, instance_id: str, units: list[TreatmentUnit], actions: list[TacticalAction], config: TacticalConfig | None = None, created_utc: datetime | None = None) → TacticalProgram[source]

Validate and assemble a tactical program.

Parameters:
  • program_id (str) – Program id.

  • instance_id (str) – Instance id.

  • units (list of TreatmentUnit) – Units.

  • actions (list of TacticalAction) – Actions.

  • config (TacticalConfig, optional) – Settings.

  • created_utc (datetime, optional) – Creation time.

Returns:

TacticalProgram – Program and named violations.

brushline.tactical.program.validate_tactical_inputs(units: list[TreatmentUnit], actions: list[TacticalAction]) → ContractValidation[source]

Validate unit/action references, methods, seasons, and duplicate ids.

Parameters:
Returns:

ContractValidation – Errors and counts.