brushline.strategic.dynamic_program

The single-segment state/action dynamic program, transition validation, backward induction, policy, and expected outcomes.

Single-segment finite-horizon dynamic program for strategic policy.

The dynamic program works on discrete P4 state classes. A state/action transition row carries a one-period probability, service attainment, risk, and uncertainty. The scalar reward is explicit: service and cost weights are declared, and the policy value is the discounted expected reward. The result also keeps the separate expected cost, service, risk, and uncertainty so a report never hides the vector behind the scalar.

class brushline.strategic.dynamic_program.DPState(*, state_id: Annotated[str, MinLen(min_length=1)], state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'], age_years: Annotated[int | None, Ge(ge=0)] = None, label: str = '')[source]

Bases: BaseModel

One strategic state.

Parameters:
  • state_id (str) – Stable state id.

  • state_class (str) – P4 state class.

  • age_years (int or None, optional) – Age in years.

  • label (str, optional) – Human label.

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

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

class brushline.strategic.dynamic_program.DynamicProgram(*, schema_version: ~typing.Literal['brushline.strategic-dp.v1'] = 'brushline.strategic-dp.v1', program_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], states: ~typing.Annotated[list[~brushline.strategic.dynamic_program.DPState], ~annotated_types.MinLen(min_length=1)], actions: ~typing.Annotated[list[~brushline.strategic.dynamic_program.StrategicAction], ~annotated_types.MinLen(min_length=1)], transitions: ~typing.Annotated[list[~brushline.strategic.dynamic_program.Transition], ~annotated_types.MinLen(min_length=1)], horizon: ~typing.Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=100)], discount_rate: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = 0.0, initial_state: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], terminal_values: dict[str, float] = <factory>, service_weight: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, risk_weight: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, uncertainty_weight: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, cost_weight: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.001, created_utc: ~datetime.datetime)[source]

Bases: BaseModel

A single-segment finite-horizon dynamic program.

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

  • program_id (str) – Program id.

  • segment_id (str) – Segment id.

  • states (list of DPState) – States.

  • actions (list of StrategicAction) – Actions.

  • transitions (list of Transition) – Transition rows.

  • horizon (int) – Number of periods.

  • discount_rate (float) – Annual discount rate from 0 to 1.

  • initial_state (str) – Initial state id.

  • terminal_values (dict of str to float) – Terminal value by state.

  • service_weight (float) – Reward weight for service attainment.

  • risk_weight (float) – Reward penalty for risk.

  • uncertainty_weight (float) – Reward penalty for uncertainty.

  • cost_weight (float) – Reward penalty per cost unit.

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

model_config = {'extra': 'forbid'}

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

exception brushline.strategic.dynamic_program.DynamicProgramError[source]

Bases: ValueError

Raised when a dynamic program is inconsistent.

class brushline.strategic.dynamic_program.DynamicProgramResult(*, schema_version: str = 'brushline.strategic-dp-result.v1', program_id: str, segment_id: str, policy: list[PolicyDecision], values: list[dict[str, float]], initial_state: str, policy_value: float, expected_cost: Annotated[float, Ge(ge=0)], expected_service_attainment: Annotated[float, Ge(ge=0), Le(le=1)], expected_risk: Annotated[float, Ge(ge=0), Le(le=1)], expected_uncertainty: Annotated[float, Ge(ge=0), Le(le=1)], discount_rate: float, horizon: int)[source]

Bases: BaseModel

The solved policy and its expected outcomes.

Parameters:
  • schema_version ({"brushline.strategic-dp-result.v1"}) – Schema version.

  • program_id (str) – Program id.

  • segment_id (str) – Segment id.

  • policy (list of PolicyDecision) – One decision per state and period.

  • values (list of dict of str to float) – State value by period, including the terminal period.

  • initial_state (str) – Initial state.

  • policy_value (float) – Value at the initial state and period zero.

  • expected_cost (float) – Discounted expected cost.

  • expected_service_attainment (float) – Discounted average service attainment.

  • expected_risk (float) – Discounted average risk.

  • expected_uncertainty (float) – Discounted average uncertainty.

  • discount_rate (float) – Discount rate.

  • horizon (int) – Horizon.

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

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

action_for(period: int, state_id: str) → str[source]

Return the policy action for a period and state.

Parameters:
  • period (int) – Period.

  • state_id (str) – State id.

Returns:

str – Action id.

Raises:

KeyError – When the period/state is not in the policy.

class brushline.strategic.dynamic_program.PolicyDecision(*, period: Annotated[int, Ge(ge=0)], state_id: str, action_id: str, value: float)[source]

Bases: BaseModel

One action in the optimal policy.

Parameters:
  • period (int) – Period from zero.

  • state_id (str) – State id.

  • action_id (str) – Action id.

  • value (float) – State value under the policy.

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

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

class brushline.strategic.dynamic_program.StrategicAction(*, action_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], label: str = '', method: ~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'] | None = None, intensity: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)] = 0.0, season: ~typing.Literal['spring', 'summer', 'fall', 'winter', 'any'] = 'any', cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, currency: str = 'CAD', available_states: list[str] = <factory>)[source]

Bases: BaseModel

One strategic action.

Parameters:
  • action_id (str) – Stable action id.

  • label (str) – Human label.

  • method (str or None) – Treatment method; None means no treatment.

  • intensity (float) – Treatment intensity from 0 to 1.

  • season (str) – Season.

  • cost (float) – Cost per application.

  • currency (str) – Currency.

  • available_states (list of str) – States where the action is available. Empty means all states.

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

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

class brushline.strategic.dynamic_program.Transition(*, from_state: Annotated[str, MinLen(min_length=1)], action_id: Annotated[str, MinLen(min_length=1)], to_state: Annotated[str, MinLen(min_length=1)], probability: Annotated[float, Gt(gt=0), Le(le=1)], service_attainment: Annotated[float, Ge(ge=0), Le(le=1)], risk: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]

Bases: BaseModel

One state/action/outcome transition.

Parameters:
  • from_state (str) – Source state id.

  • action_id (str) – Action id.

  • to_state (str) – Destination state id.

  • probability (float) – Probability from 0 to 1.

  • service_attainment (float) – Service attainment from 0 to 1.

  • risk (float) – Risk index from 0 to 1.

  • uncertainty (float) – Uncertainty index from 0 to 1.

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

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

brushline.strategic.dynamic_program.solve_dynamic_program(program: DynamicProgram) → DynamicProgramResult[source]

Solve the dynamic program by backward induction and replay its policy.

Parameters:

program (DynamicProgram) – Program.

Returns:

DynamicProgramResult – Policy, values, and expected outcomes.

Raises:

DynamicProgramError – When the program is invalid.

brushline.strategic.dynamic_program.validate_dynamic_program(program: DynamicProgram) → ContractValidation[source]

Validate references, availability, and transition probabilities.

Parameters:

program (DynamicProgram) – Program.

Returns:

ContractValidation – Errors and counts.