This repository contains Python quickstarts for SolverForge, a 100% Timefold-compatible AI constraint solver. The original Timefold solver for Python has been discontinued by Timefold and the original team is focusing on the Java and Kotlin solvers. A roadmap to provide community support for Python is currently under review.
Priority for this repository is closing the performance gap between the Java and Python quickstarts by providing optimized solutions for all use cases.
- The original quickstarts have been moved to legacy/. These are based on unified Pydantic data models for API and constraint solving
- In fast/ we are incrementally refactoring quickstarts to employ more efficient data models that limit Pydantic to API boundary validation to reduce overhead during solver moves
- In benchmarks/ we are running benchmarks to assess the performance of the different implementations
Current results are available in the benchmarks directory:
You can also find our assessment of said results in report.md.
Currently, fast quickstarts are available for the employee-scheduling, meeting scheduling and vehicle-routing use cases, exclusively.
Being unofficial, this repository is not directly affiliated with Timefold AI, but maintainers are in touch with the Timefold AI team.
It shows different use cases and basic implementations of constraint solving in Python.
| Use Case |
Notable Solver Concepts |
|---|---|
| 🚚 Vehicle Routing | Chained Through Time, Shadow Variables |
| 🧑💼 Employee Scheduling | Load Balancing |
| 🛠️ Maintenance Scheduling | TimeGrain, Shadow Variable, Variable Listener |
| 📦 Food Packaging | Chained Through Time, Shadow Variables, Pinning |
| 🛒 Order Picking | Chained Planning Variable, Shadow Variables |
| 🏫 School Timetabling | Timeslot |
| 🏭 Facility Location Problem | Shadow Variable |
| 🎤 Conference Scheduling | Timeslot, Justifications |
| 🛏️ Bed Allocation Scheduling | Allows Unassigned |
| 🛫 Flight Crew Scheduling | |
| 👥 Meeting Scheduling | TimeGrain |
| ✅ Task Assigning | Bendable Score, Chained Through Time, Allows Unassigned |
| 📆 Project Job Scheduling | Shadow Variables, Variable Listener, Strenght Comparator |
| 🏆 Sports League Scheduling | Consecutive Sequences |
| 🏅 Tournament Scheduling | Pinning, Load Balancing |
Note
The implementations in this repository serve as a starting point and/or inspiration when creating your own application. Timefold Solver is a library and does not include a UI. To illustrate these use cases a rudimentary UI is included in these quickstarts.
Find the most efficient routes for vehicles to reach visits, considering vehicle capacity and time windows when visits are available. Sometimes also called "CVRPTW".
- Run vehicle-routing (Python, FastAPI)
- Run vehicle-routing (fast) (Python, FastAPI)
Tip
Schedule shifts to employees, accounting for employee availability and shift skill requirements.
- Run employee-scheduling (Python, FastAPI)
- Run employee-scheduling (fast) (Python, FastAPI)
Tip
Schedule maintenance jobs to crews over time to reduce both premature and overdue maintenance.
- Run maintenance-scheduling (Python, FastAPI)
Schedule food packaging orders to manufacturing lines to minimize downtime and fulfill all orders on time.
- Run food-packaging (Python, FastAPI)
Generate an optimal picking plan for completing a set of orders.
- Run order-picking (Python, FastAPI)
Assign lessons to timeslots and rooms to produce a better schedule for teachers and students.
- Run school-timetabling (Python, FastAPI)
Without a UI:
- Run hello-world-school-timetabling (Java, Maven or Gradle)
Pick the best geographical locations for new stores, distribution centers, COVID test centers, or telecom masts.
- Run facility-location (Python, FastAPI)
Assign conference talks to timeslots and rooms to produce a better schedule for speakers.
- Run conference-scheduling (Python, FastAPI)
Assign beds to patient stays to produce a better schedule for hospitals.
- Run bed-allocation-scheduling (Python, FastAPI)
Assign crew to flights to produce a better schedule for flight assignments.
- Run flight-crew-scheduling (Python, FastAPI)
Assign timeslots and rooms for meetings to produce a better schedule.
- Run meeting-scheduling (Python, FastAPI)
- Run meeting-scheduling (fast) (Python, FastAPI)
Assign employees to tasks to produce a better plan for task assignments.
- Run task-assigning (Python, FastAPI)
Assign jobs for execution to produce a better schedule for project job allocations.
- Run project-job-scheduling (Python, FastAPI)
Assign rounds to matches to produce a better schedule for league matches.
- Run sports-league-scheduling (Python, FastAPI)
Tournament Scheduling service assigning teams to tournament matches.
- Run tournament-scheduling (Python, FastAPI)
This version of Timefold Quickstarts was forked on 03 August 2025 from the original Timefold Quickstarts, which was entirely Apache-2.0 licensed (a permissive license).
The original Timefold Quickstarts was forked on 20 April 2023 from OptaPlanner Quickstarts.
This version of Timefold Quickstarts is a derivative work of the original Timefold Quickstarts and OptaPlanner Quickstarts, which includes copyrights of the original creators, Timefold AI, Red Hat Inc., affiliates, and contributors, that were all entirely licensed under the Apache-2.0 license. Every source file has been modified.