brushline.tactical.timeline

Geo points, timeline configuration, operation events, and the deterministic timeline builder.

Operations timeline and 3D data contract.

class brushline.tactical.timeline.GeoPoint(*, latitude: Annotated[float, Ge(ge=-90), Le(le=90)], longitude: Annotated[float, Ge(ge=-180), Le(le=180)], height_m: float | None = None)[source]

Bases: BaseModel

A known position.

Parameters:
  • latitude (float) – Latitude.

  • longitude (float) – Longitude.

  • height_m (float or None) – Optional height.

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

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

class brushline.tactical.timeline.OperationEvent(*, event_id: str, event_type: str, timestamp: datetime, work_order_id: str, action_id: str, unit_id: str, segment_ids: list[str], crew_id: str, machine_id: str | None = None, cost: Annotated[float, Ge(ge=0)], position: GeoPoint | None = None, position_status: str)[source]

Bases: BaseModel

One timestamped operation event.

Parameters:
  • event_id (str) – Event id.

  • event_type ({"start", "finish"}) – Event type.

  • timestamp (datetime) – Timestamp.

  • work_order_id (str) – Source work order.

  • action_id (str) – Source action.

  • unit_id (str) – Unit.

  • segment_ids (list of str) – Segments.

  • crew_id (str) – Crew.

  • machine_id (str or None) – Machine.

  • cost (float) – Cost on the start event; zero on finish.

  • position (GeoPoint or None) – Known position.

  • position_status ({"known", "unknown"}) – Position state.

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

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

model_post_init(_OperationEvent__context: object) → None[source]

Validate event type and position consistency.

class brushline.tactical.timeline.OperationsTimeline(*, schema_version: Literal['brushline.tactical-timeline.v1'] = 'brushline.tactical-timeline.v1', timeline_id: str, instance_id: str, source_plan_id: str, events: list[OperationEvent], total_cost: Annotated[float, Ge(ge=0)], unknown_position_events: Annotated[int, Ge(ge=0)], created_utc: datetime)[source]

Bases: BaseModel

A deterministic operations timeline.

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

  • timeline_id (str) – Timeline id.

  • instance_id (str) – Instance id.

  • source_plan_id (str) – Source operations plan.

  • events (list of OperationEvent) – Events.

  • total_cost (float) – Work-order cost.

  • unknown_position_events (int) – Events without a known position.

  • 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.timeline.TimelineConfig(*, start_time: datetime, shift_hours: Annotated[float, ~annotated_types.Gt(gt=0), ~annotated_types.Le(le=24)] = 8.0, positions: dict[str, ~brushline.tactical.timeline.GeoPoint]=<factory>)[source]

Bases: BaseModel

Timeline settings.

Parameters:
  • start_time (datetime) – Start timestamp.

  • shift_hours (float) – Event duration.

  • positions (dict of str to GeoPoint) – Known positions by work-order id. Missing ids are unknown, not invented.

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

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

brushline.tactical.timeline.build_operations_timeline(*, timeline_id: str, instance_id: str, plan: OperationsPlan, config: TimelineConfig, created_utc: datetime | None = None) → OperationsTimeline[source]

Build start/finish events without inventing positions.

Parameters:
  • timeline_id (str) – Timeline id.

  • instance_id (str) – Instance id.

  • plan (OperationsPlan) – Operations plan.

  • config (TimelineConfig) – Settings.

  • created_utc (datetime, optional) – Creation time.

Returns:

OperationsTimeline – Timeline.