AI Scheduler Maker

A tools to generate timetable that are complicated, with the feature of adjusting using gemini 3 pro as the core helper

Comment

AI Timetable Maker: Solving the School Scheduling Crisis (Solo Project)

Inspiration

This project started from a problem I kept seeing over and over again in educational institutions: timetabling is painful.

For school administrators, creating a timetable feels like playing 3D Tetris with real consequences. It can take days—or even weeks—to manually align teachers, classes, rooms, and time slots without conflicts. Worse, a single change—like a teacher becoming unavailable or a room being closed—can break the entire schedule and force a full rebuild.

I realized that while this feels like a human coordination problem, it is fundamentally a Constraint Satisfaction Problem (CSP). Instead of just digitizing spreadsheets, I wanted to build a system that actually solves the scheduling puzzle—compressing weeks of manual work into seconds of computation.

What the Project Does

AI Timetable Maker is an intelligent scheduling system that automatically generates and adjusts academic timetables.

Automatic Schedule Generation

The system takes structured inputs—Teachers, Rooms, Subjects, and Assigned Classes—and computes a conflict-free timetable. It enforces real-world constraints such as:

  • Teacher availability
  • Room capacity
  • Student cohort (grade-level) consistency

Smart Block Scheduling (SKS-Aware)

Unlike basic schedulers, the system understands credit-based scheduling (SKS):

  • A 3-credit course is placed as a continuous 3-hour block.
  • Large courses (e.g., 6 credits) are automatically split into feasible sessions, such as two 3-hour blocks.

This allows the system to adapt to real university and high-school curricula.

AI-Powered Adjustments

Instead of manually editing schedules, users can interact using natural language:

  • “Dr. Alan cannot teach on Mondays”
  • “The Gym is unavailable on Friday afternoons”

The AI interprets these instructions, updates the scheduling constraints, and regenerates a valid timetable instantly.

How I Built It

I designed the system as a hybrid between deterministic optimization and AI-driven interaction.

Backend

  • Python + FastAPI for a lightweight, high-performance API.

Database

  • Firebase Firestore as the main database.
  • Although Firestore is NoSQL, I designed a relational-like structure.
  • An assigned_classes collection acts as a contract linking Teachers, Subjects, and Student Cohorts, ensuring consistency during scheduling.

Solver Engine

  • Google OR-Tools (CP-SAT) powers the core scheduling logic.
  • It handles hard constraints such as:
    • No double-booking of teachers or rooms
    • Room capacity limits
    • Time-slot exclusivity

The solver guarantees that every generated timetable is mathematically valid.

AI Agent

  • Integrated Google Gemini 2.5 Flash as a natural language interface.
  • The AI converts user input into structured JSON actions (e.g., block_teacher, unblock_room), which are then executed by the backend.
  • This design keeps the AI focused on intent understanding, while the solver handles execution.

Challenges I Faced

Variable-Duration Class Scheduling

Scheduling single-hour classes is straightforward. Scheduling multi-hour labs is not.

For block classes, the system must find:

  • Consecutive empty time slots
  • Shared availability across teachers, rooms, and student cohorts

To solve this, I implemented logic to pre-calculate valid start times before passing constraints to the solver.

Relational Logic in a NoSQL Database

Scheduling is inherently relational, but Firestore is document-based.
Designing a schema that:

  • Avoids duplication
  • Preserves data integrity
  • Remains efficient for constraint solving

required several iterations, especially around the assigned_classes collection.

Natural Language Precision

Natural language commands like:

“Remove the restriction for Math”

require multiple internal steps:

  • Identify the correct Subject ID
  • Modify its unavailable_slots
  • Trigger a rescheduling process

Achieving reliable behavior required careful prompt engineering and strict schema validation.

Key Accomplishments

Hybrid Intelligence Architecture

I successfully combined:

  • A deterministic constraint solver (OR-Tools)
  • A probabilistic LLM (Gemini)

This ensures schedules are always valid while keeping the system intuitive to use.

Dynamic Constraint Repair

The /adjust endpoint allows real-time constraint changes using plain language. Watching the solver recompute a valid schedule in seconds after a single sentence was one of the most rewarding parts of the project.

Real-World Curriculum Support

Support for SKS splitting allows the system to handle realistic academic workloads, making it suitable for both schools and universities.

What I Learned

Constraint-Based Thinking

This project forced me to shift from procedural programming to constraint-based modeling—a crucial skill for solving NP-hard problems like scheduling.

Clear Separation of Roles for AI

Letting the AI generate schedules directly caused hallucinations and invalid outputs.
Using AI for intent interpretation and code for execution proved to be the most reliable and scalable approach.

What’s Next

Frontend Interface

I am currently designing a React-based frontend with a drag-and-drop timetable grid to visualize the generated_schedule collection.

Soft Constraints

All current constraints are hard constraints.
Next, I plan to add soft constraints, such as:

  • “Teacher A prefers morning classes”

This will allow the solver to optimize for preference and comfort, not just feasibility.

Multi-School Scalability

I plan to extend the architecture to support multiple schools or departments simultaneously within the same system.

This project represents my approach to combining algorithmic rigor with human-centered AI design, solving a real-world problem through both mathematics and machine intelligence.

Gemini Integration: Technical Overview

The AI Timetable Maker leverages Gemini 3 Flash (gemini-3-flash-preview) as the core reasoning engine. The integration is architected around three key technical patterns:

  1. Backend Response Schema Enforcement

We utilize Gemini's structured generation capabilities within the Python backend. By passing Pydantic models (JSON Schemas) directly to the API, this enforce strictly typed output for all agent actions. This ensures the model returns executable data structures (e.g., ForceSubject objects) rather than unstructured text, preventing parsing errors and enabling direct database operations.

  1. Context Injection for Semantic Mapping

The application implements dynamic context injection at the prompt level. We serialize the current database state (Teachers, Rooms, Subjects) into the prompt context. This allows the model to perform semantic mapping—resolving natural language references (e.g., "Dr. Alan") to internal database UUIDs (t_alan) and translating temporal descriptions into specific grid coordinates (Mon_1).

  1. AI-Assisted Code Generation

Google AI Studio serves as the primary prototyping environment. It allows for the iterative design of prompts and schemas, which are then exported as production-ready Python code. This workflow accelerates the development of the ai_agent.py module by automating the generation of the client configuration and model parameters.

Built With

Share this project:

Updates