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:
BaseModelOne 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:
BaseModelA 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:
ValueErrorRaised 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:
BaseModelThe 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].
- class brushline.strategic.dynamic_program.PolicyDecision(*, period: Annotated[int, Ge(ge=0)], state_id: str, action_id: str, value: float)[source]
Bases:
BaseModelOne 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:
BaseModelOne 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:
BaseModelOne 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.