Kronos - Gerador de Horários Escolares

Gerador automático de horários escolares para IFMT Bela Vista, usando OR-Tools CP-SAT e gerando PDFs profissionais coloridos.

Destaques

• Gera horários ótimos usando solver de restrições OR-Tools CP-SAT
• Suporta 10 restrições hard e 2 soft (aulas consecutivas, preferência de turno)
• Especifica indisponibilidade de professores por dia e período
• Exporta para 7 formatos: PDF, Markdown, Excel, iCal, CSV, HTML e PNG
• Formato YAML simples para fácil edição manual
• Validação completa dos dados de entrada com mensagens de erro claras
• Análise de estatísticas e detecção de conflitos
• Controle de versão com diff visual entre horários
• Restrições avançadas: max aulas/dia, intervalo professor, balanceamento curricular
• Interface web completa com CRUD, geração assíncrona, progresso em tempo real e downloads

Guia Detalhado

Para instruções completas sobre como criar os arquivos de entrada YAML e entender todas as capacidades do Kronos, consulte o GUIDE.md.

Visão Geral

O Kronos é um gerador de horários escolares simplificado focado em desenvolvimento de algoritmos, usando arquivos YAML para entrada e gerando saídas em Markdown e PDF. É projetado para os cursos do IFMT Bela Vista.

O sistema usa OR-Tools CP-SAT (Programação por Restrições) para resolver o problema de agendamento de horários, garantindo uma solução ótima que respeita todas as restrições especificadas.

Pré-requisitos

• Python 3.11 ou superior
• pip (gerenciador de pacotes Python)

Instalação

Crie um ambiente virtual e instale as dependências:

make venv

Isso cria .venv/ e instala todos os pacotes necessários de requirements.txt.

Para instalar/atualizar dependências em um ambiente virtual existente:

make install

Início Rápido

Inicie a interface web e acesse http://localhost:8000:

make web

A interface permite:

• Visualizar e editar todos os dados (horários, salas, disciplinas, professores, turmas)
• Gerar horários com indicador de progresso em tempo real
• Visualizar a grade colorida por disciplina
• Baixar arquivos gerados (PDF, Excel, HTML, PNG, etc.)

Para uso via linha de comando (avançado):

python -m kronos --validate-only --data-dir meus_dados

Uso

Comandos Makefile

make help              # Mostrar todos os comandos disponíveis
make venv              # Criar ambiente virtual e instalar dependências
make install           # Instalar/atualizar dependências no venv existente
make web               # Iniciar interface web (http://localhost:8000)
make clean             # Remover arquivos gerados
make test              # Executar testes

Argumentos de Linha de Comando

A interface web é o método principal de uso. O CLI permanece disponível para cenários avançados:

# Validar dados sem gerar
python -m kronos --validate-only

# Usar diretório de dados personalizado
python -m kronos --data-dir meus_dados

# Ver opções disponíveis
python -m kronos --help

Configuração

Os dados de entrada são arquivos YAML em server/data/. Para detalhes completos sobre o formato de cada arquivo, consulte o GUIDE.md.

Para testar rapidamente:

make web

Estrutura dos arquivos

• horarios.yaml - Horários disponíveis (dias/períodos) e metadados
• salas.yaml - Salas disponíveis, capacidades e restrições
• professores.yaml - Professores, disciplinas e indisponibilidades
• disciplinas.yaml - Definições de disciplinas e cores de exibição
• turmas.yaml - Turmas e aulas semanais

Para exemplos detalhados de cada arquivo, veja GUIDE.md.

Estrutura do Projeto

kronos/
├── client/                # Frontend SPA
│   └── index.html         # Interface web completa
├── server/                # Backend
│   ├── kronos/            # Pacote Python
│   │   ├── __init__.py
│   │   ├── models.py      # Dataclasses
│   │   ├── loader.py      # Carregamento YAML
│   │   ├── scheduler.py   # OR-Tools CP-SAT
│   │   ├── validator.py   # Validação
│   │   ├── web/
│   │   │   └── app.py     # FastAPI + rotas REST
│   │   └── ...            # generators, analyzer, etc.
│   ├── data/              # Dados YAML de entrada
│   ├── exports/           # Arquivos gerados (PDF, MD, etc.)
│   └── requirements.txt   # Dependências Python
├── .venv/                 # Ambiente virtual
├── Makefile
├── README.md
├── LICENSE
├── GUIDE.md
├── FEATURES_MISSING.md
└── ROADMAP_NEW.md

Desenvolvimento

make venv              # Criar ambiente virtual (primeira vez)
make install           # Instalar/atualizar dependências
make web               # Iniciar interface web
make test              # Executar testes
make clean             # Remover arquivos gerados

Algoritmo

Restrições obrigatórias (hard):

1. Cada aula é agendada exatamente uma vez
2. Professor não pode ter aulas simultâneas
3. Turma não pode ter aulas simultâneas
4. Sala não pode hospedar aulas simultâneas
5. Aulas da mesma disciplina são distribuídas em dias diferentes
6. Professores respeitam restrições de indisponibilidade
7. Salas respeitam disciplinas permitidas

Restrições preferenciais (soft): 8. Aulas consecutivas (quando configurado) — maximizadas na função objetivo

Capacidades adicionais

• Geração múltipla: Gere até N soluções diferentes com --num-solutions
• Estatísticas: Analise ocupação de salas, carga de professores, janelas livres
• Detecção de conflitos: Verifique sobreposições indesejadas
• Controle de versão: Salve e compare diferentes versões de horários
• Múltiplos formatos: PDF, Markdown, Excel, iCal, CSV, HTML

Tratamento de Erros

Se o sistema retornar "Nenhuma solução viável encontrada", verifique:

1. Horários e salas suficientes para todas as aulas
2. Restrições de disponibilidade dos professores não são excessivas
3. Capacidade total (salas × horários) ≥ número total de aulas

Para calcular a capacidade:

• Salas: contadas em salas.yaml
• Horários: contados em horarios.yaml
• Aulas: soma de aulas_semanais em turmas.yaml

Contribuindo

Contribuições são bem-vindas! Veja FEATURES_MISSING.md para funcionalidades planejadas e ROADMAP_NEW.md para cronograma de implementação.

Licença

Licença MIT - Veja o arquivo LICENSE para detalhes.