1

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:

  1. 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.
  2. 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:

ItemQuantidade
Turmas38 (18 do Ensino Médio Integrado e 20 da graduação)
Docentes63
Disciplinas249
Tempos de aula semanais a alocar890

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

  1. 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.
  2. 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.
  3. Validar a solução fora do solver dá confiança. Um motor de regras independente funciona como um teste automatizado permanente da modelagem.
  4. 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.
Carregando publicação patrocinada...