Shift scheduling API

Deterministic FHOPS-style crew and equipment shift scheduling.

This is a small operational prototype, not a FHOPS engine replacement. It turns tactical work items into crew-day and machine-day assignments, respecting method skills, daily shift hours, travel time, and contractor identity.

class brushline.tactical.shifts.ShiftAssignment(*, work_order_id: str, unit_id: str, year: int, day: Annotated[int, Ge(ge=1)], crew_id: str, machine_id: str | None, method: str, start_hour: Annotated[float, Ge(ge=0), Le(le=24)], end_hour: Annotated[float, Ge(ge=0), Le(le=24)], productive_hours: Annotated[float, Gt(gt=0)], travel_hours: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

One work item chunk assigned to a crew and optional machine.

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

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

class brushline.tactical.shifts.ShiftConfig(*, max_days_per_year: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=366)] = 260, include_travel: bool = True, blocked_days: dict[int, list[int]]=<factory>)[source]

Bases: BaseModel

Scheduler limits.

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

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

class brushline.tactical.shifts.ShiftCrew(*, crew_id: Annotated[str, MinLen(min_length=1)], methods: Annotated[list[str], MinLen(min_length=1)], shift_hours: Annotated[float, Gt(gt=0), Le(le=24)] = 8.0, contractor_id: str | None = None)[source]

Bases: BaseModel

One crew resource.

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

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

exception brushline.tactical.shifts.ShiftError[source]

Bases: ValueError

Raised when shift inputs are inconsistent.

class brushline.tactical.shifts.ShiftMachine(*, machine_id: Annotated[str, MinLen(min_length=1)], methods: Annotated[list[str], MinLen(min_length=1)], shift_hours: Annotated[float, Gt(gt=0), Le(le=24)] = 8.0, contractor_id: str | None = None)[source]

Bases: BaseModel

One machine resource.

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

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

class brushline.tactical.shifts.ShiftPlan(*, schema_version: ~typing.Literal['brushline.tactical-shifts.v1'] = 'brushline.tactical-shifts.v1', plan_id: str, instance_id: str, assignments: list[~brushline.tactical.shifts.ShiftAssignment], total_productive_hours: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], total_travel_hours: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], crew_utilization: dict[str, float], machine_utilization: dict[str, float], feasible: bool, violations: list[~brushline.tactical.shifts.ShiftViolation] = <factory>, created_utc: ~datetime.datetime)[source]

Bases: BaseModel

A deterministic crew/equipment shift plan.

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

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

class brushline.tactical.shifts.ShiftViolation(*, code: str, message: str, work_order_id: str | None = None)[source]

Bases: BaseModel

One named scheduling violation.

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

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

class brushline.tactical.shifts.ShiftWorkItem(*, work_order_id: Annotated[str, MinLen(min_length=1)], unit_id: Annotated[str, MinLen(min_length=1)], method: Annotated[str, MinLen(min_length=1)], year: Annotated[int, Ge(ge=1900), Le(le=2200)], hours: Annotated[float, Gt(gt=0)], travel_hours: Annotated[float, Ge(ge=0)] = 0, contractor_id: str | None = None, priority: int = 0)[source]

Bases: BaseModel

One tactical action to schedule.

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

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

brushline.tactical.shifts.build_shift_plan(*, plan_id: str, instance_id: str, work_items: list[ShiftWorkItem], crews: list[ShiftCrew], machines: list[ShiftMachine], config: ShiftConfig | None = None, created_utc: datetime | None = None) → ShiftPlan[source]

Assign work items to crews, machines, days, and shift-hour windows.

Parameters:
  • plan_id (str) – Plan id.

  • instance_id (str) – Instance id.

  • work_items (list of ShiftWorkItem) – Tactical work items.

  • crews (list of ShiftCrew) – Crews and their method skills.

  • machines (list of ShiftMachine) – Machines and their method skills.

  • config (ShiftConfig, optional) – Day and travel settings.

  • created_utc (datetime, optional) – Creation time.

Returns:

ShiftPlan – Assignments, utilization, and named violations.

Raises:

ShiftError – If ids are duplicated or a work item has no positive hours.