Timetable

Open-source scheduling engine

The school week, solved.

Model groups, teachers, rooms, availability, and shared sessions. Let CP-SAT find a schedule you can verify.

View source Quick start
Translucent course blocks arranged inside a physical timetable grid
SolverGoogle OR-Tools CP-SAT
InterfacePython and CLI
DataVersioned JSON schemas
LicenseApache-2.0
Overhead view of shared course blocks spanning a modular timetable

A timetable is more than a filled grid.

Every lesson competes for people, rooms, and time. Timetable models those relationships explicitly, then checks the result independently.

Read the problem format

From requirements to a result you can inspect.

Each boundary stays visible, testable, and useful on its own.

  1. Describe

    Declare the school week, workloads, resources, and availability in JSON.

  2. Validate

    Catch malformed data and broken references before optimization starts.

  3. Solve

    Apply hard constraints and minimize preference penalties with CP-SAT.

  4. Verify

    Check the solution independently, then export JSON and CSV files.

Constraints that match an actual school week.

The backend already handles the relationships that make manual scheduling difficult.

Flexible structure

Courses can meet alone or together.

Schedule fixed groups, flexible combinations, and shared sessions without flattening them into special cases.

Shared blue course blocks crossing adjacent time slots
Resource safety

No hidden collisions.

Teachers, teaching teams, student groups, and rooms cannot occupy two places at once.

Time rules

Availability and duration stay intact.

Respect breaks, daily limits, blocked periods, and uninterrupted multi-period sessions.

Independent trust

The solver does not grade its own work.

A separate validator checks generated sessions and structured diagnostics explain impossible inputs.

Backend first. Nothing hidden.

Clone the repository, validate the fictional example, and generate a schedule from the command line.

View the roadmap 
$ git clone https://github.com/aldahiiir/timetable.git
$ cd timetable
$ pip install -e '.[dev]'

$ timetable validate examples/basic_school/problem.json
Problem is valid.

$ timetable solve examples/basic_school/problem.json
Solver status: OPTIMAL

Test it against the messy parts of scheduling.

The public backend preview is ready for early technical and usability feedback.

View source Report an issue