A clearer planning horizon for drivers.

01 / The problem

Availability is a forecast; dispatch is a decision

The central constraint is that a driver's next usable time and location change with the current trip. En-route arrivals, unloading, rest and already planned shipments each require different context. Predicting availability too early can make a nominally attractive next trip impractical.

The scheduler makes idle time and distance explicit. Reports show how opportunities are distributed across drivers.

02 / Inside the system

From operational records to recommendations

Operational JSON arrives through a storage-backed ingestion stage. Driver-grouped records update a PostgreSQL workspace containing drivers, shipments, assignments, agreements and predictions. The model stage reads trips that need new predictions and assembles status-dependent inputs: timestamps, ETA, current and planned locations, rest dates and agreement context.

Parsed availability dates and coordinates are persisted before matching begins. The assignment stage combines that estimate with driver restrictions and shipment requirements, writes an assignment status of Recommended, and exports UTC, local-time and operations reports. A Flask API orchestrates the three stages in order: ingestion, prediction, then assignment.

Scroll →

Operational workspace

Python ingestion and a PostgreSQL database connect driver, shipment, assignment and prediction records.

Prediction and allocation

A fine-tuned chat-completion model supplies the availability estimate; SciPy matching applies deterministic scheduling costs.

Application handoff

Flask orchestration, job status and exported operations reports provide the integration surface.

03 / Inside the system

Teach the model the availability question

The supervised preparation guide defines logistics fields and scenarios for different trip states. For unfinished trips, a label can begin with arrival, ETA or scheduled delivery and add average unloading time; completed trips instead use recorded departure time. User and assistant messages turn that context into supervised examples. The fine-tuned availability model's task is therefore a bounded time-and-location estimate, rather than deciding the whole dispatch plan.

The batch code targets a fine-tuned model, and the January 2025 guide sets out the preparation and training settings. The application selects its model through configuration and uses the fine-tuned availability model.

Runtime code obtains two predictions and selects between them with date-difference heuristics. It parses dates and coordinates, retries transient requests and skips a driver when essential output cannot be validated. Agreement between the two responses is a consistency check on the output; forecast quality is judged against the availability observed later.

04 / Inside the system

Keep scheduling policy outside the model

The specialist model step feeds a deterministic scheduler. Agreement vetoes, required certifications, driver and operation restrictions, maximum shipment distance, pickup proximity and idle-time limits restrict candidate pairs. For the strict and relaxed matching passes, the cost combines weighted idle time and distance to pickup. SciPy's linear assignment function performs the Hungarian matching; a separate greedy pass handles priority shipments first.

After each pass, assigned shipments are removed and driver availability is advanced before the remaining work is considered. If a pass allocates all remaining work, later passes are skipped and the output is exported. The strict pass uses standard thresholds. The relaxed pass broadens configured distance and idle limits and can permit late pickup when configured. The application records the pass and the unmatched reasons, so a planner can see which policy produced each recommendation.

Distance uses a geographic approximation and a road-distance factor, with travel-time and buffer assumptions. Pickup timing remains the dispatcher's judgment.

Scroll →

05 / Inside the system

A long-running plan needs a completion contract

The API starts the pipeline in a background thread and immediately returns a job identifier. A separate status endpoint exposes component results and distinguishes completion, partial success and error. This design addressed the hosting platform's request-time limit.

Job state is held in the application process, and the wrapper reports completion from the subprocess exit status. The status endpoint shows each component's result separately. Acceptance of the initial HTTP request marks the start of the job, not its completion.

06 / Inside the system

Three decisions shape the system

The important choices concern the boundary of the model, the explicit scheduling policy and the handoff of long-running work. Their costs remain visible even when the interface presents one planning action.

1. Decision 01

   Estimate availability before allocating work

   Use a bounded model estimate followed by deterministic scheduling.

   Forecast uncertainty and mandatory operating restrictions can be examined separately.

   Trade-off. A match still inherits errors in its input availability estimate.

2. Decision 02

   Make allocation cost explicit

   Use a priority greedy pass, then strict and relaxed Hungarian matching with idle-time and distance costs.

   The scheduler can reject prohibited pairs and compare the feasible alternatives using visible terms.

   Trade-off. Relaxed thresholds and approximate travel assumptions need the planner's review.

3. Decision 03

   Expose long work as a job

   Return a job identifier and component status from the API.

   The hosting platform's request-time limit made request acceptance and pipeline completion separate events.

   Trade-off. Job state lives in the application process, and completion follows the subprocess exit status.

07 / Inside the system

Measure the forecast and the resulting work separately

Forecast quality and planning outcomes are separate questions. Forecast quality is the gap between predicted and observed availability. Planning outcomes are waiting time, use of recommendations, opportunity distribution, driver experience and driver retention over a defined period.

The preparation guide shuffles generated scenarios into training, validation and test sets. Because scenarios are correlated and some labels derive from timestamps already in the input, a random split can measure rule reproduction rather than future availability. A forecasting comparison separates drivers and time periods, scores the same inputs against a rules baseline, and uses observed availability as the reference.

Operational evaluation asks a different question: did the recommendation fit, was it used, and what happened to waiting time and opportunity distribution? The diagram separates the system's output from the observations that answer those questions.

Scroll →

How is forecast quality checked?

The application checks that each prediction is usable: it requests two responses, compares them, and validates the time and coordinates. Forecast accuracy is measured separately, by comparing predictions with observed availability and with a rules baseline.

Does a feasible pairing guarantee an on-time pickup?

No. Distance uses a geographic approximation with a road-distance factor, travel-time and buffer assumptions, so the dispatcher checks pickup timing before committing a trip.

What does the cost function include?

Weighted idle time and distance to pickup, inside the feasibility rules.

08 / Inside the system

Connect model work, application work and dispatch

Embedding Labs linked the operating problem to data preparation, prediction, constrained assignment and customer integration, working with technical contributors. The client supplies the operational setting and retains dispatch judgment.

A successful handoff needs more than a model response. It connects the operational data contract, the meaning of Recommended, job completion and the planner's response.