Gerando a grade horária de um campus inteiro em 2 minutos com OR-Tools: o caso do Kairós
Quem já trabalhou numa coordenação de ensino sabe: montar a grade horária é um quebra-cabeça. Cruzar turmas, disciplinas e a disponibilidade de cada professor, sem choques, com cada carga horária fechando certinho, consome tempo e quase sempre termina com alguma troca de última hora que desmonta outra parte da grade.
Neste post conto como construí o Kairós, uma aplicação web que gera automaticamente a grade horária do IFMT Campus Pontes e Lacerda – Fronteira Oeste. O trabalho foi apresentado em formato de resumo simples, com banner, na XIII JEnPEx (Jornada de Ensino, Pesquisa e Extensão) do campus, com o título "Gestão de grades horárias no ensino técnico: uma solução web para conciliação de preferências docentes e diretrizes institucionais".
O problema
A montagem de grades horárias é um problema combinatório clássico, estudado há décadas na literatura de timetabling (Schaerf, 1999). O número de combinações possíveis cresce muito rápido, e uma solução que parece boa num canto da grade pode criar um conflito em outro.
No IFMT existe ainda uma camada extra: a grade precisa respeitar os limites à jornada docente definidos pela Resolução nº 68/2023 – RTR-CONSUP/RTR/IFMT. Entre outros pontos, ela determina:
- no máximo dois turnos diários por docente;
- intervalo mínimo de 11 horas entre um dia de trabalho e outro (a interjornada).
Ou seja, não basta evitar choques. A grade tem que ser válida do ponto de vista normativo, e ainda seria bom que ela respeitasse as preferências de cada professor.
Levantamento de requisitos
Antes de escrever código, sentei com a coordenação e o departamento de ensino para entender como a grade era montada na prática. Duas decisões saíram dessas conversas:
- Não mudar o fluxo de entrada. A coordenação já trabalhava com uma planilha de horários, e é por ela que as preferências docentes chegam. O sistema importa essa planilha em vez de exigir um cadastro novo.
- A coordenação continua no controle. O sistema gera a grade, mas quem decide os ajustes finais são as pessoas. Por isso o painel precisava explicar as decisões, não só mostrar o resultado.
Arquitetura
- Front-end: React
- Back-end: NestJS + PostgreSQL
- Otimização: módulo em Python com o solver CP-SAT do Google OR-Tools
O NestJS cuida de cadastros, importação, versões e regras de negócio. Quando é hora de gerar a grade, os dados vão para o módulo Python, que monta o modelo de otimização e devolve a solução.
Modelando as regras: duras e brandas
A decisão mais importante do projeto foi separar as regras em dois grupos, seguindo a abordagem consolidada na literatura de timetabling (Burke; Petrovic, 2002).
Regras obrigatórias (hard constraints), que nunca podem ser violadas:
- sem choque de horário entre docentes ou entre turmas;
- carga semanal exata de cada disciplina;
- aulas no turno da turma;
- aulas fixas (horários que já vêm definidos);
- até dois turnos diários por docente;
- interjornada de 11 horas.
Regras desejáveis (soft constraints), modeladas como penalidades ponderadas:
- dias preferidos do docente no campus;
- aulas em blocos (duas aulas seguidas da mesma disciplina, em vez de picadas);
- disciplina não repetida no mesmo dia;
- equilíbrio da distribuição semanal.
O CP-SAT busca uma grade que cumpra todas as regras obrigatórias e, entre as soluções válidas, a que tiver a menor penalidade total. Os pesos permitem dizer ao solver o que importa mais. Por exemplo, respeitar o dia preferido de um professor pode valer mais do que manter duas aulas em bloco.
Um motor de regras independente
Um detalhe que considero essencial: cada solução do solver é conferida por um motor de regras separado. O solver e o validador não compartilham a mesma lógica.
Isso tem duas vantagens. A primeira é que, se houver um bug na modelagem do solver, o validador pega. A segunda é que o mesmo motor de regras é usado quando a coordenação faz ajustes manuais, então uma alteração feita à mão passa pela mesma checagem que a grade gerada automaticamente.
O painel: ajuste fino sem quebrar regra
A grade gerada é um ponto de partida. Na prática, sempre aparece um ajuste que só quem conhece o campus sabe que precisa ser feito.
Por isso o painel foi pensado para que a coordenação possa mover aulas com segurança. Ao arrastar uma aula, o sistema indica para cada horário se ela:
- pode ir sem problemas;
- pode ir com ressalva (marcação "leve"), por exemplo quando a troca deixa um professor com um horário vago entre aulas ou quebra um bloco;
- não deveria ir (marcação "grave"), por exemplo quando a turma passaria a ter duas aulas no mesmo horário.
E, principalmente, o painel explica o motivo de cada bloqueio em linguagem simples, como "A turma INF-3-VESP tem duas aulas no mesmo horário na terça-feira, às 15:50". A coordenação não precisa adivinhar por que algo não encaixa.
O sistema também registra o histórico de versões da grade, o que permite recuperar versões anteriores e dá mais transparência às decisões.
Resultados
O Kairós foi testado com os dados reais previstos para o 2º semestre de 2026:
| Item | Quantidade |
|---|---|
| Turmas | 38 (18 do Ensino Médio Integrado e 20 da graduação) |
| Docentes | 63 |
| Disciplinas | 249 |
| Tempos de aula semanais a alocar | 890 |
Nesse cenário, a aplicação gerou uma grade completa em aproximadamente dois minutos, sem violar nenhuma regra obrigatória.
O ganho não está só no tempo de geração. O trabalho da coordenação deixa de ser montar a grade do zero e passa a ser conferir e fazer ajustes pontuais, com o sistema avisando na hora se alguma regra está sendo quebrada.
O que aprendi
- Ouvir antes de modelar. As melhores decisões do projeto, como importar a planilha que já existia e explicar os bloqueios, vieram das conversas com quem monta a grade de verdade.
- Separar regras duras de preferências é o que torna o problema tratável. Tentar tratar tudo como obrigatório geralmente leva a um problema sem solução. Com penalidades ponderadas, o solver sempre encontra a melhor grade possível dentro das regras.
- Validar a solução fora do solver dá confiança. Um motor de regras independente funciona como um teste automatizado permanente da modelagem.
- Explicabilidade importa mais do que parece. Um sistema que só diz "não pode" gera desconfiança. Um que diz "não pode, por causa disto" vira ferramenta de trabalho.
Próximos passos
O Kairós ainda não está em uso oficial. Os próximos passos são:
- exportar a grade no layout oficial da instituição;
- criar uma área em que cada docente consulte a própria grade;
- realizar o teste de aceitação com a coordenação, condição para o uso oficial no campus.
Agradecimentos
Agradeço aos servidores do departamento de ensino e da coordenação do IFMT Campus Pontes e Lacerda – Fronteira Oeste que participaram do levantamento de requisitos. Sem essas conversas, o projeto seria só mais um solver resolvendo o problema errado.
Se você já trabalhou com timetabling, OR-Tools ou gestão acadêmica, quero saber nos comentários: como vocês lidam com as preferências docentes? Pesos fixos, níveis de prioridade ou outra abordagem?
Referências
- BURKE, Edmund K.; PETROVIC, Sanja. Recent research directions in automated timetabling. European Journal of Operational Research, v. 140, n. 2, p. 266–280, 2002.
- GOOGLE. OR-Tools: CP-SAT solver. 2026. Disponível em: https://developers.google.com/optimization/cp/cp_solver.
- INSTITUTO FEDERAL DE EDUCAÇÃO, CIÊNCIA E TECNOLOGIA DE MATO GROSSO (IFMT). Conselho Superior. Resolução nº 68/2023 – RTR-CONSUP/RTR/IFMT, de 15 de junho de 2023. Cuiabá: IFMT, 2023.
- SCHAERF, Andrea. A survey of automated timetabling. Artificial Intelligence Review, v. 13, n. 2, p. 87–127, 1999.